muse-codes 0.1.7

Typed Rust SDK for Meta's Muse Code terminal agent: serde models of the `muse exec --json` JSONL event stream, plus an async (Tokio) client for headless Muse Code runs.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

# muse-codes

Typed Rust SDK for [Meta's Muse Code](https://dev.meta.ai/docs) terminal
coding agent.

Muse Code's headless mode (`muse exec --json`) emits an event-sourced JSONL
journal on stdout: envelope records covering command intake, run lifecycle,
task lifecycle, and streamed output. This crate types that stream and ships
an async Tokio client for driving headless runs.

Tested against Muse Code 0.1.0 (`0.1.0-R708.1`). The crate version may
carry a patch offset above the CLI release for crate-side additions.

## Captured, not guessed

Muse publishes no schema and no official SDK, so the wire is the contract:

- All models derive from **committed captures of real CLI output**
  (`test_cases/*.jsonl`), taken via the credential-free `--provider echo`
  mode plus live Muse Spark runs (basic, tool-use, multi-subagent) for
  the provider-only vocabulary (`run.model.configured`, `tool.result`,
  streamed/cancelled/rejected/status lifecycle events).
- The envelope keeps its payload as raw JSON (byte-faithful round-trips);
  [`MuseRecord::typed_payload`] lifts it into a typed `MusePayload`, and
  payload types not yet observed (the journal also records approvals,
  edits, and subagent lifecycle under a live provider) come back as
  `MusePayload::Unknown` instead of failing.
- A nightly workflow re-captures echo runs against the freshly installed
  CLI, fingerprints `payload_type → field set`, and files an issue on any
  drift from the committed snapshot
  (`tests/schemas/muse_stream_fingerprint.txt`).

## Features

| Feature | Description | WASM-compatible |
|---------|-------------|-----------------|
| `types` | Journal envelope + payload models (serde only) | Yes |
| `async-client` | Tokio client spawning `muse exec --json` | No |

`default = ["types", "async-client"]`.

## Quick start

```rust,ignore
use muse_codes::{ExecRun, MuseExecBuilder, MusePayload, Provider};

let run = ExecRun::spawn(
    &MuseExecBuilder::new("summarize this repo").provider(Provider::Meta),
).await?;

let terminal = run.wait_terminal(|record| {
    if let Ok(MusePayload::RunOutputDelta(d)) = record.typed_payload() {
        print!("{}", d.text);
    }
}).await?;
println!("\nterminal: {}", terminal.terminal);
```

The Meta provider needs credentials (`muse login`, `META_API_KEY`, or
`~/.config/muse/auth.json`); `Provider::Echo` runs without any.

`MuseExecBuilder` covers the full `muse exec` flag surface (worktrees,
sandbox/safety toggles, context compaction, image attachments, prompt
files, step/output caps — see the builder docs), with each flag verified
against the real binary and the CLI's cross-flag constraints noted on the
corresponding method.

## Auth helpers

No PTY needed — Muse's auth surface is automation-friendly:

```rust,ignore
use muse_codes::auth::{auth_set, credentials_present, DeviceLoginFlow};

// API key path (CI):
auth_set(&std::env::var("MY_META_KEY")?, None).await?;

// Or the browser device-code path:
let mut flow = DeviceLoginFlow::start().await?;
let dc = flow.device_code(std::time::Duration::from_secs(20)).await?;
println!("Open {} and confirm code {}", dc.verification_url, dc.code);
flow.wait_approved(std::time::Duration::from_secs(300)).await?;
assert!(credentials_present());
```

## Record identity — read this before persisting or rendering

Journal record `id`s are **UUID-shaped counters, not UUIDs**. They restart
at the same value for every session, so two sessions emit byte-identical id
lists; and `sequence` restarts on every turn. Neither is a safe handle
alone.

- Unique key: the composite **`(stream.id, id)`**
- Turn grouping: `causation_id`
- Ordering **within** a turn: `sequence`

Treat `id` as stream-local *everywhere* — dedup, correlation maps, and
frontend list keys included (a render key of `id` alone would alias rows
across sessions). `stream.id` is the only cross-session-unique handle;
supply your own via [`MuseExecBuilder::session_id`] and it is adopted
verbatim.

## Known wire gaps (Muse Code 0.1.0)

Things the stream does *not* carry, which consumers must work around:

- **`tool.result` has no `task_id`** — but a correlation exists. The wire
  models each tool call as its own task (`task_kind: tool.<tool_name>`),
  and the result's `correlation_facts.tool_name` names it: in every
  committed capture, each `tool.result` matches exactly one such task.
  Match on that, latest-first. Do **not** use a recency-of-running-tasks
  heuristic — measured against the captures it always mis-attributes,
  because the issuing tool task has already completed by the time its
  result record lands (only `reminder.*` scaffolding is still running).
  The `call_id` is a provider call id, not a task handle; the residual
  ambiguity (two same-name tool tasks genuinely concurrent) still needs
  the field upstream.
- **No usage/token accounting** appears anywhere in the observed stream.
- **No approval round-trip**: policy decisions are journaled after the fact
  (`side_effect_intent.policy_decision`), never asked, so headless runs
  cannot be gated interactively.

## Testing

- **Corpus tests**: every committed capture line must parse, lift into a
  known typed payload, round-trip byte-faithfully, and satisfy envelope
  invariants (schema version, monotone sequences, durability classes).
- **Live test** (`--features integration-tests`): drives a real
  echo-provider run through the typed client to its terminal record —
  needs `muse` on `PATH`, no credentials.