README
¶
box-evidence-harness
A headless fake box. It drives the exact Voice-Agent WebSocket path the
kombify-Box firmware uses and reports the two runtime facts the firmware
hardcodes against — so the ESP32 firmware in kombify-box (milestones
M1.3/M1.4) never bakes in a stale server assumption.
This is the SpeechKit side of the box roadmap's M1.0 Server-Evidence-Harness.
What it proves
- Empty-Origin dial is accepted. The ESP32 sends no
Originheader. The server default-denies that, so it must runSPEECHKIT_ALLOW_EMPTY_ORIGIN=1. The harness dials with no Origin (viapkg/speechkit/client, which sends onlyAuthorization+ the ticket subprotocol) and fails loudly if rejected. - Downlink is 24 kHz. The firmware upsamples the response 24→48 kHz. The harness cross-checks the response PCM byte count against the output transcript's word count (~2.5 synthesized words/sec); the rate whose implied duration best matches is the server's true downlink rate. Drift from 24 kHz fails the run.
It also confirms the full turn: Bearer session create → ticket → WS dial →
start{provider:"deepgram"} → state:listening → streamed 16 kHz utterance →
input_transcript → response audio.
Run
From the repo root (so the default fixture path resolves), against a server that
has a Deepgram key and SPEECHKIT_ALLOW_EMPTY_ORIGIN=1:
export SPEECHKIT_SERVER_URL=https://speechkit.kombify.io
export SPEECHKIT_TOKEN=<service-bearer>
go run ./examples/box-evidence-harness -verbose
Flags: -server, -token, -provider (default deepgram), -audio (default
testdata/e2e/voiceagent/turn1.wav, 16 kHz S16LE mono), -timeout, -verbose.
Exit codes / result line
The last stdout line is machine-readable: RESULT: passed, RESULT: fail, or
RESULT: blocked_by_auth.
| Code | Meaning |
|---|---|
0 |
Evidence PASS. |
2 |
blocked_by_auth — no token, or session create returned 401/403. CI treats this as skipped. |
1 |
Hard failure — dial rejected, no listening, empty transcript, no audio, or downlink-rate drift. |
Note:
go runcollapses a non-zero program exit to1. For a true exit code,go build -o box-evidence-harness ./examples/box-evidence-harnessand run the binary, or parse theRESULT:line. The CI gate does the former.
Documentation
¶
Overview ¶
Command box-evidence-harness is a headless "fake box": it drives the exact Voice-Agent WebSocket path the kombify-Box firmware uses and reports the two runtime facts the firmware hardcodes against.
Flow (mirrors kombify-box milestones M1.2-M1.4):
- Bearer POST /v1/voiceagent/sessions -> single-use ticket.
- WS dial with Sec-WebSocket-Protocol: ticket.<t> and NO Origin header (the ESP32 sends none; the server must run SPEECHKIT_ALLOW_EMPTY_ORIGIN=1).
- start{provider:"deepgram"} within 5 s -> state:listening.
- Stream a 16 kHz S16LE mono utterance, then audio_end.
- Collect input_transcript + response audio until the turn ends.
It then reports:
- EMPTY-ORIGIN accepted: proves the server config the firmware relies on.
- DOWNLINK ~24 kHz: cross-checks the response PCM byte count against the output-transcript word count so the firmware's 24->48 kHz upsampler is not built on a stale rate assumption.
This is a repo/CI evidence tool, not a distributable client. It reuses the public SDK (pkg/speechkit/client) so it also doubles as a minimal net_ws reference. See ROADMAP.md (v0.49.0 M1) and the box repo's docs/roadmap-standalone-voice.md (M1.0).
Exit codes: 0 = evidence PASS, 2 = blocked_by_auth (no token / 401 / 403; CI treats this as skipped), 1 = hard failure (dial rejected, no listening, empty transcript, no audio, or downlink rate drift).
Source Files