test(slice-2): integration test + Python echo brain + LEARNING pointers
- 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.
This commit is contained in:
46
examples/echo_brain/README.md
Normal file
46
examples/echo_brain/README.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user