soothe-client 0.3.2

WebSocket client for talking to a running soothe-daemon
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

# soothe-client (Rust)

Talk to a running **soothe-daemon** over WebSocket — send prompts, stream agent
turns, run jobs.

```bash
cargo add soothe-client
```

Requires a local daemon (default `ws://127.0.0.1:8765`).

## Quick start

```rust
use soothe_client::appkit::{DaemonSession, SendTurnOptions};
use soothe_client::TEXT_COMPLETION;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let session = DaemonSession::new("ws://127.0.0.1:8765", None);
    session.connect(None).await?;
    session
        .send_turn(
            "Summarize this in one sentence: agents need tools.",
            Some(SendTurnOptions {
                intent_hint: Some(TEXT_COMPLETION.into()),
                ..Default::default()
            }),
        )
        .await?;
    for chunk in session.iter_turn_chunks(None).await? {
        println!("{} {:?}", chunk.mode, chunk.data);
    }
    session.close().await?;
    Ok(())
}
```

More patterns: [`examples/`](examples/) (hello → streaming → multi-turn → pool → jobs).

Route to a specialist with `preferred_subagent` (canonical ids:
`deep_research`, `academic_research`, `browser_use`, `planner`):

```rust
use soothe_client::{Client, SendInputOptions};

# async fn demo() -> Result<(), soothe_client::errors::Error> {
let client = Client::new("ws://127.0.0.1:8765");
client.connect().await?;
client
    .send_input(
        "Research recent agent evaluation benchmarks",
        SendInputOptions {
            preferred_subagent: Some("deep_research".into()),
            ..Default::default()
        },
    )
    .await?;
# Ok(())
# }
```

## What you get

| Need | Use |
|------|-----|
| One conversation, stream replies | `appkit::DaemonSession` |
| Jobs / cron (async) | `AsyncCommandClient` |
| Jobs / cron (scripts / sync) | `CommandClient` |
| Raw WebSocket / custom RPCs | `Client` |
| Many users / HTTP backend | `ConnectionPool` + `TurnRunner` (+ optional `SseBroadcaster`) |

`DaemonSession` uses a dual-socket layout (stream + RPC sidecar): peels leftover
prior-goal terminals, applies early chunk filtering, ignores premature
`soothe.stream.end` until the turn has progress, drains a short post-idle window,
and sends `delivery_ack` on terminal frames.

`TurnRunner` ends turns via `TurnBoundary` (gated `stream.end` / idle / stopped),
with pre-send settle-drain and arm-before-end so pooled leftovers cannot end the
next turn early.

## Develop

```bash
make check                 # fmt + clippy + unit tests
make test-integration      # live suite (needs soothed)
make test-examples         # live 01–06 (needs soothed)
```

## Compatibility

Same protocol-1 WebSocket contract as `soothe-client-python`,
`soothe-client-go`, and `@mirasoth/soothe-client`.

## License

MIT