411276bfde
- Integration test: smoke test against in-process EchoServer (hello handshake round-trip). Full end-to-end + reconnect-path tests adapt to slice-1's existing integration-test harness. - examples/echo_brain/: Python reference brain (~80 lines, websockets lib). README documents runtime posture + why a Python brain complements the Rust one (language-agnosticism vs wire-types-reusability). - LEARNING.md: 5 new pointers (mpsc/oneshot, VecDeque ring, async WS, Box<dyn Trait> field widening, zero-sized marker newtype). Spec ref: 2026-06-28-slice-2-agent-tap-design.md §8.4, §8.5 #7.
47 lines
1.6 KiB
Markdown
47 lines
1.6 KiB
Markdown
# Rutster Echo Brain (Python reference)
|
|
|
|
The canonical foreign-language brain for slice-2. Speaks the [slice-2 tap wire
|
|
protocol](../../docs/superpowers/specs/2026-06-28-slice-2-agent-tap-design.md) (§3):
|
|
versioned JSON events over `ws://` text frames with base64-encoded
|
|
little-endian PCM.
|
|
|
|
## Why a Python brain?
|
|
|
|
The architecture (ARCHITECTURE.md §"Agent tap") names "a Python script" as the
|
|
canonical brain persona. This example proves the wire format is language-agnostic:
|
|
the core's `rutster-tap` Rust types serialize/deserialize to exactly what
|
|
`json.loads` + `websockets` produces. The Rust echo brain (`crates/rutster-tap-echo`)
|
|
proves wire-types reusability from outside the core; this Python brain proves
|
|
language-agnosticism.
|
|
|
|
## Run
|
|
|
|
```bash
|
|
pip install -r examples/echo_brain/requirements.txt
|
|
python examples/echo_brain/echo_brain.py
|
|
# [echo_brain] listening on ws://127.0.0.1:8081/echo
|
|
```
|
|
|
|
Then in another terminal:
|
|
|
|
```bash
|
|
cargo run # the core dials out to ws://127.0.0.1:8081/echo by default
|
|
```
|
|
|
|
## Not in CI
|
|
|
|
This script is **not** run by CI. The Rust `rutster-tap-echo` crate covers
|
|
the in-process test surface for the integration test; this Python brain is
|
|
the human-runnable demo + manual e2e test plan.
|
|
|
|
## Protocol
|
|
|
|
See [the spec](../../docs/superpowers/specs/2026-06-28-slice-2-agent-tap-design.md)
|
|
§3 for the full wire protocol. Key behavior:
|
|
|
|
- On `hello`: ack with `hello` (echo the `session_id`).
|
|
- On `audio_in`: echo the same PCM back as `audio_out` (advisory — core
|
|
disposes).
|
|
- On `bye` / `session_end`: close cleanly.
|
|
- Stateless across reconnects (spec §5.3) — every `hello` starts fresh.
|