refactor: remove in-process loopback; symmetric build-time transport selection (#66)

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: tarotene

.github/workflows/ci.yml

@@ -25,6 +25,11 @@ jobs:
         with:
           components: rustfmt, clippy
 
+      - name: Install system libudev (required by serialport on Linux)
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libudev-dev pkg-config
+
       - name: Cache Cargo artifacts
         uses: Swatinem/rust-cache@v2
 
@@ -37,10 +42,25 @@ jobs:
       - name: Run tests
         run: cargo test --workspace
 
-      - name: Smoke test loopback-demo
+      - name: Smoke test host-pty-server
         run: |
-          timeout 30 cargo run -p loopback-demo | tee /tmp/loopback-demo.out
-          grep -qF "ping -> 0xDEADBEEF" /tmp/loopback-demo.out
+          cargo build -p host-pty-server
+          cargo build --manifest-path tools/telepath-shell/Cargo.toml --no-default-features --features serial
+          cargo run -p host-pty-server > /tmp/server.out &
+          SERVER_PID=$!
+          trap 'kill "$SERVER_PID" 2>/dev/null || true; wait "$SERVER_PID" 2>/dev/null || true' EXIT
+          for i in $(seq 1 15); do
+            SLAVE=$(grep 'HOST_PTY_SERVER_PATH=' /tmp/server.out 2>/dev/null | sed 's/HOST_PTY_SERVER_PATH=//' | head -1 || true)
+            if [ -n "$SLAVE" ]; then break; fi
+            sleep 1
+          done
+          if [ -z "$SLAVE" ]; then
+            echo "host-pty-server did not print PTY path within 15s"
+            cat /tmp/server.out
+            exit 1
+          fi
+          tools/telepath-shell/target/debug/telepath-shell --port "$SLAVE" --exec ping | tee /tmp/shell.out
+          grep -qF "ping -> 0xDEADBEEF" /tmp/shell.out
 
       - name: Test MCP server (workspace-excluded)
         working-directory: tools/telepath-mcp-server

AGENTS.md

@@ -10,20 +10,23 @@
 | `telepath-wire` | Shared wire protocol types | server + client |
 | `telepath-macros` | `#[command]` proc-macro | server (build time only) |
 | `telepath-server` | Target-side RPC server library | `thumbv7em-none-eabi` |
-| `telepath-client` | Host-side RPC client library | native (`std`) |
-| `examples/loopback-demo` | In-process server+client loopback | native (`std`) |
+| `telepath-client` | Host-side RPC client library; `rtt` and `serial` Cargo features select the transport | native (`std`) |
+| `examples/host-pty-server` | Host-side server deployment over a PTY pair (hardware-free regression) | native (`std`) |
 | `examples/nrf52840-ping` | Reference server deployment on nRF52840-DK | `thumbv7em-none-eabi` |
-| `tools/telepath-shell` | Interactive shell for Telepath servers | native (`std`) |
-| `tools/telepath-mcp-server` | MCP server — discovers commands, exposes as MCP tools | native (`std`) |
+| `tools/telepath-shell` | Interactive shell for Telepath servers; `default = ["rtt"]`, `serial` opt-in | native (`std`) |
+| `tools/telepath-mcp-server` | MCP server — discovers commands, exposes as MCP tools; `default = ["rtt"]`, `serial` opt-in | native (`std`) |
 
 ## Build Commands
 
 ```
-# Host workspace (all 5 members including loopback-demo)
+# Host workspace (all 5 members including host-pty-server)
 cargo build --workspace
 
-# Run the in-process loopback end-to-end (no hardware required)
-cargo run -p loopback-demo
+# Run host-pty-server (prints slave PTY path; connect telepath-shell --features serial to that path)
+cargo run -p host-pty-server
+
+# Full hardware-free smoke via just (spawns server + serial shell, asserts ping)
+just host-pty-smoke
 
 # Host tests
 cargo test --workspace
@@ -35,15 +38,19 @@ cd examples/nrf52840-ping && cargo build --release
 cd examples/nrf52840-ping && cargo run --release
 
 # Shell tool (excluded from workspace — requires cd)
+# Default build: RTT transport (--features rtt, the default)
 cd tools/telepath-shell && cargo build
 cd tools/telepath-shell && cargo run -- ping
 cd tools/telepath-shell && cargo run
+# Serial build: CDC-ACM / PTY transport
+cd tools/telepath-shell && cargo build --no-default-features --features serial
+cd tools/telepath-shell && cargo run --no-default-features --features serial -- --port /dev/ttyACM0
 
 # MCP server (excluded from workspace — requires cd)
 cd tools/telepath-mcp-server && cargo build
 cd tools/telepath-mcp-server && cargo test
-cd tools/telepath-mcp-server && cargo run -- --transport loopback
-cd tools/telepath-mcp-server && cargo run -- --transport rtt --chip nRF52840_xxAA
+cd tools/telepath-mcp-server && cargo run
+cd tools/telepath-mcp-server && cargo run --no-default-features --features serial -- --port /dev/ttyACM0
 
 # Format check
 cargo fmt --all -- --check
@@ -68,11 +75,12 @@ just ci
 - Cross-compilation REQUIRES `rustup target add thumbv7em-none-eabi`.
 - `cargo run --release` invokes `probe-rs download` (flash + exit). The probe is released immediately so `telepath-shell` can attach.
 
-### `examples/loopback-demo`
+### `examples/host-pty-server`
 - IS a workspace member (`std` target, no cross-compile). Build with `cargo build --workspace`.
-- MUST exercise the full wire path including COBS framing — it is the primary hardware-free regression for `telepath-server` and `telepath-client`.
+- MUST exercise the full wire path including COBS framing via a real PTY transport — it is the primary hardware-free regression for `telepath-server` and the serial path of `telepath-client`.
 - MUST use only public APIs of the dependent crates; it MUST NOT poke internal state to aid the round-trip.
-- CI runs `timeout 30 cargo run -p loopback-demo` and grep-asserts the `ping -> 0xDEADBEEF` output on every push.
+- On startup, prints `HOST_PTY_SERVER_PATH=<path>` to stdout then flushes; the test harness reads this to obtain the slave device path.
+- CI spawns `host-pty-server` in background, reads the slave path, runs `telepath-shell --features serial --port <path> --exec ping`, and grep-asserts `ping -> 0xDEADBEEF`.
 
 ### `tools/telepath-shell`
 - MUST be built separately; it is excluded from the workspace.
@@ -166,6 +174,6 @@ git config --local core.hooksPath .githooks
 
 - `pre-commit` → `just fmt-check` (sub-second; runs on every commit)
 - `pre-push` → `just clippy` + `just test` (~30 s; runs before every push)
-- `just ci` (fmt-check + clippy + test + emulator) SHOULD be run before opening a PR.
+- `just ci` (fmt-check + clippy + test + host-pty-smoke + mcp-test) SHOULD be run before opening a PR.
 - `just firmware-ping` SHOULD additionally be run when the PR touches wire / macros /
   server / client / shell / nrf52840-ping (see "Commit and PR Rules" above).

Cargo.toml

@@ -5,7 +5,7 @@ members = [
     "telepath-macros",
     "telepath-server",
     "telepath-client",
-    "examples/loopback-demo",
+    "examples/host-pty-server",
 ]
 exclude = ["examples/nrf52840-ping", "tools/telepath-shell", "tools/telepath-mcp-server"]
 

Justfile

@@ -53,14 +53,29 @@ mcp-test:
 
 # Run telepath-mcp-server against a flashed nRF52840-DK (firmware must already be flashed)
 mcp-run-rtt:
-    cd tools/telepath-mcp-server && cargo run -- --transport rtt
+    cd tools/telepath-mcp-server && cargo run
 
 # Build everything: workspace + firmware + CLI + MCP server
 check-all: build firmware-build cli-build mcp-build
 
-# Run the in-process emulator end-to-end (no hardware required)
-emulator:
-    cargo run -p loopback-demo
-
-# Full CI gate: fmt-check + clippy + test + emulator smoke + mcp-test
-ci: fmt-check clippy test emulator mcp-test
+# Smoke test host-pty-server end-to-end via serial telepath-shell (no hardware required)
+host-pty-smoke:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    cargo build -p host-pty-server
+    cargo build --manifest-path tools/telepath-shell/Cargo.toml --no-default-features --features serial
+    cargo run -p host-pty-server > /tmp/host-pty-server.out &
+    SERVER_PID=$!
+    trap 'kill "$SERVER_PID" 2>/dev/null || true; wait "$SERVER_PID" 2>/dev/null || true' EXIT
+    for i in $(seq 1 15); do
+        SLAVE=$(grep 'HOST_PTY_SERVER_PATH=' /tmp/host-pty-server.out 2>/dev/null | sed 's/HOST_PTY_SERVER_PATH=//' | head -1 || true)
+        if [ -n "$SLAVE" ]; then break; fi
+        sleep 1
+    done
+    if [ -z "$SLAVE" ]; then
+        echo "ERROR: host-pty-server did not print PTY path"; exit 1
+    fi
+    tools/telepath-shell/target/debug/telepath-shell --port "$SLAVE" --exec ping | tee /dev/stderr | grep -qF "ping -> 0xDEADBEEF"
+
+# Full CI gate: fmt-check + clippy + test + host-pty smoke + mcp-test
+ci: fmt-check clippy test host-pty-smoke mcp-test

README.md

@@ -52,7 +52,7 @@ sequenceDiagram
 | `telepath-macros` | `#[command]` proc-macro |
 | `telepath-server` | Target-side RPC server — `no_std` |
 | `telepath-client` | Host-side RPC client — `std` |
-| `examples/loopback-demo` | In-process server+client emulator — no hardware required |
+| `examples/host-pty-server` | Host-side server deployment over a PTY pair — hardware-free regression |
 | `examples/nrf52840-ping` | Reference server deployment on nRF52840-DK (workspace-excluded) |
 | `tools/telepath-shell` | Interactive shell for Telepath servers — REPL and one-shot commands (workspace-excluded) |
 | `tools/telepath-mcp-server` | MCP server — exposes discovered commands as MCP tools (workspace-excluded) |
@@ -84,7 +84,7 @@ from an AI agent without hand-written tool descriptors.
   (`NamedType` serialised with postcard) over the wire.
 - `client.discover()` fetches all commands via CDP paging; the result lands in
   `SchemaCache`, keyed by command ID.
-- `examples/loopback-demo` exercises this end-to-end — no hardware required.
+- `examples/host-pty-server` exercises this end-to-end over a real PTY transport — no hardware required.
 
 ### MCP tool auto-generation
 
@@ -121,7 +121,7 @@ The fastest way to see Telepath in action requires no hardware.
 ```
 git clone https://github.com/tarotene/telepath.git
 cd telepath
-cargo run -p loopback-demo
+just host-pty-smoke
 ```
 
 Expected output:
@@ -130,10 +130,10 @@ Expected output:
 ping -> 0xDEADBEEF
 ```
 
-The emulator runs a `TelepathServer` and `TelepathClient` on two OS threads
-connected by `std::sync::mpsc` byte channels. The full wire path
-(postcard serialization + COBS framing) executes identically to real hardware.
-Switching to an MCU is purely a transport swap.
+`host-pty-smoke` starts `examples/host-pty-server` (a `TelepathServer` over a PTY
+master), then drives it from `telepath-shell --features serial` via the slave end.
+The full wire path (postcard serialization + COBS framing) runs identically to real
+hardware. Switching to an MCU is purely a transport swap.
 
 ## Prerequisites
 

examples/loopback-demo/Cargo.toml examples/host-pty-server/Cargo.tomlexamples/loopback-demo/Cargo.toml renamed to examples/host-pty-server/Cargo.toml

@@ -1,17 +1,18 @@
 [package]
-name = "loopback-demo"
+name = "host-pty-server"
 version.workspace = true
 edition.workspace = true
 license.workspace = true
-description = "Hardware-free loopback demo: full wire round-trip via mpsc channels"
+description = "Host-side Telepath server deployment over a PTY pair (parallel to nrf52840-ping)"
 
 [[bin]]
-name = "loopback-demo"
+name = "host-pty-server"
 path = "src/main.rs"
 
 [dependencies]
 telepath-wire   = { workspace = true }
 telepath-server = { workspace = true }
-telepath-client = { workspace = true }
 postcard        = { version = "1", features = ["alloc"] }
 heapless        = { workspace = true }
+anyhow          = "1"
+nix             = { version = "0.29", features = ["term", "fs"] }

examples/host-pty-server/README.md

@@ -0,0 +1,68 @@
+# host-pty-server
+
+Hardware-free regression server: full wire round-trip over a real PTY pair.
+
+Opens a PTY with `openpty(3)`, prints the slave device path, then runs a
+`TelepathServer` on the master side in a poll loop. A client (e.g.
+`telepath-shell --no-default-features --features serial`) connects to the slave end and speaks the
+full Telepath wire protocol — COBS framing + postcard serialization — over
+the PTY byte stream.
+
+## Run
+
+```
+cargo run -p host-pty-server
+```
+
+The process prints one line to stdout and then keeps running:
+
+```
+HOST_PTY_SERVER_PATH=/dev/pts/3
+```
+
+Connect a client to the printed path:
+
+```
+cd tools/telepath-shell
+cargo run --no-default-features --features serial -- --port /dev/pts/3 --exec ping
+```
+
+Or use `just host-pty-smoke` to run the full two-process smoke automatically.
+
+## Expected output (smoke)
+
+```
+ping -> 0xDEADBEEF
+```
+
+## What this demonstrates
+
+| Layer | Real hardware (nRF52840-DK) | This server |
+|---|---|---|
+| Transport | probe-rs RTT channel 1 | PTY master (`O_NONBLOCK` `File`) |
+| Framing | COBS, delimiter `0x00` | Identical — raw COBS bytes traverse the PTY |
+| Serialization | postcard | Identical |
+| Server | `TelepathServer` over `RttTransport` | `TelepathServer` over `PtyTransport` |
+| Client | `telepath-shell --features rtt` | `telepath-shell --features serial` |
+
+The same `telepath-server` code path executes as on real hardware. Switching
+to a real MCU is purely a transport swap — framing and serialization are
+unchanged.
+
+## Code structure
+
+```
+src/
+└── main.rs   — #[command] fns, PtyTransport impl, TelepathServer poll loop
+```
+
+## Registered commands
+
+The same four CPU-only demo commands as `examples/nrf52840-ping`:
+
+| Command | Args | Return |
+|---------|------|--------|
+| `ping` | — | `u32` (`0xDEAD_BEEF`) |
+| `add` | `i32, i32` | `i32` |
+| `crc32` | `heapless::Vec<u8, 128>` | `u32` |
+| `echo` | `heapless::Vec<u8, 128>` | `heapless::Vec<u8, 128>` |