feat(telnyx): add Telnyx assistant server framework

.github/workflows/telnyx-pion-probe.yml

@@ -0,0 +1,56 @@
+# Runs the Pion WebRTC probe against a Telnyx AI Assistant on a Linux runner.
+#
+# This exists because the probe (a native Go binary) cannot be executed on the macOS dev
+# machine where it was written -- corporate security policy SIGKILLs freshly-built unsigned
+# Mach-O binaries. A Linux GitHub runner has no such restriction, allows the outbound
+# network the probe needs, and needs NO secret: anonymous login uses only the public
+# assistant id.
+#
+# Trigger manually (Actions -> "Telnyx Pion probe" -> Run workflow) with an assistant id.
+name: Telnyx Pion probe
+
+on:
+  workflow_dispatch:
+    inputs:
+      assistant_id:
+        description: "Telnyx AI Assistant id (assistant-...)"
+        required: true
+        default: "assistant-473093df-d97a-4eae-b484-413bcbe2fda4"
+      seconds:
+        description: "Call duration (s)"
+        required: false
+        default: "45"
+  push:
+    paths:
+      - "experiments/pion-probe/**"        # build-check on changes
+
+jobs:
+  probe:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: experiments/pion-probe
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.21"
+      - name: Build (always)
+        run: go build ./...
+      - name: Vet
+        run: go vet ./...
+      - name: Run probe against the assistant (dispatch only)
+        if: github.event_name == 'workflow_dispatch'
+        run: |
+          go run . \
+            -assistant "${{ github.event.inputs.assistant_id }}" \
+            -seconds "${{ github.event.inputs.seconds }}" \
+          | tee probe.log
+          echo "----- verdict -----"
+          grep -E "ASSISTANT HEARD US|assistant heard us|ice connection state|inbound RTP" probe.log || true
+      - name: Upload log
+        if: github.event_name == 'workflow_dispatch'
+        uses: actions/upload-artifact@v4
+        with:
+          name: pion-probe-log
+          path: experiments/pion-probe/probe.log

experiments/pion-probe/.gitignore

@@ -0,0 +1,2 @@
+pion-probe
+*.test

experiments/pion-probe/README.md

@@ -0,0 +1,72 @@
+# Pion probe — does a browser-class ICE stack fix the Telnyx WebRTC path?
+
+Standalone Go program that drives the **exact** anonymous-WebRTC flow PR #173's
+`TelnyxWebRTCClient` uses (`anonymous_login` → `telnyx_rtc.invite` → answer → media), but
+with **Pion** instead of aiortc.
+
+## Why
+
+The assistant never hears EVA on the aiortc path (VSDK-277). Everything downstream — codec,
+SRTP, region, framing, nomination mode — has been excluded. The browser works, and the one
+thing it does differently is run **libwebrtc's ICE**. `aiortc` uses **aioice**, a pure-Python
+ICE agent with known nomination deviations (it still does RFC 5245 *aggressive* nomination,
+removed in RFC 8445). **Pion's ICE is a browser-class stack.** This probe answers one
+question: does Pion's ICE get caller audio through b2bua-rtc where aioice doesn't?
+
+If it prints `ASSISTANT HEARD US`, the fix is to move PR #173's media engine to Pion. If it
+fails the same way, the problem is not the client ICE stack and the escalation stands.
+
+## Run
+
+Needs Go 1.21+. **No Telnyx account or API key** — anonymous login uses only the public
+assistant id.
+
+```bash
+cd experiments/pion-probe
+go mod tidy
+go run . -assistant assistant-473093df-d97a-4eae-b484-413bcbe2fda4 -seconds 45
+```
+
+`speech.ogg` (48 kHz mono opus, committed) is streamed as the caller after the greeting.
+
+Expected on success:
+
+```
+[ws] connected
+[verto] session: <sessid>
+[assistant] Thank you for calling Summit Health Plan prior authorization support...
+[ice] connected
+[audio] streaming caller speech
+*** ASSISTANT HEARD US: "I'm calling from a provider office..." ***
+==== RESULT ====
+assistant heard us   : true (N user transcripts)
+```
+
+## Status
+
+**Builds clean; not yet run against the assistant.** It was written and compiled in an
+environment that blocks execution of freshly-built native binaries (both `go run` and a
+plain external-linked `go build` binary are killed before `main` runs — this affects a
+trivial `hello world` too, so it is a sandbox limitation, not a code issue). It needs to be
+run on a normal developer machine to get the result. `go build ./...` passes.
+
+## If it works: integrating Pion into PR #173
+
+The swap boundary is small. `TelnyxWebRTCClient` (in `telnyx_server.py`) exposes
+`start()`, `stop()`, `send_audio(pcm)`, `build_invite_params(sdp)`, an `audio_handler`
+callback, and `disconnected_event`. Everything else in PR #173 (the EVA server contract,
+Verto signaling, audio bridge, tool handling) talks only to that surface.
+
+Two integration shapes:
+
+1. **Pion as a media sidecar** (recommended): a small Go binary owns the peer connection;
+   Python keeps the Verto signaling and exchanges SDP + PCM with it over a local Unix
+   socket. `TelnyxWebRTCClient` becomes a thin wrapper that launches the sidecar. Python
+   still drives `anonymous_login`/`invite`; Go produces the offer and consumes the answer.
+
+2. **Pion owns signaling too**: move the whole client to Go, Python just spawns it and
+   bridges audio + conversation events. Cleaner separation, more Go.
+
+Either keeps PR #173 on the **anonymous `assistant_id`** path — no account, no ingress —
+which is the hard constraint. This probe is shape (2) collapsed into one file, so it doubles
+as the skeleton for the sidecar.

experiments/pion-probe/go.mod

@@ -0,0 +1,31 @@
+module eva/pion-probe
+
+go 1.21
+
+require (
+	github.com/google/uuid v1.6.0
+	github.com/gorilla/websocket v1.5.3
+	github.com/pion/webrtc/v4 v4.0.7
+)
+
+require (
+	github.com/pion/datachannel v1.5.10 // indirect
+	github.com/pion/dtls/v3 v3.0.4 // indirect
+	github.com/pion/ice/v4 v4.0.3 // indirect
+	github.com/pion/interceptor v0.1.37 // indirect
+	github.com/pion/logging v0.2.2 // indirect
+	github.com/pion/mdns/v2 v2.0.7 // indirect
+	github.com/pion/randutil v0.1.0 // indirect
+	github.com/pion/rtcp v1.2.15 // indirect
+	github.com/pion/rtp v1.8.10 // indirect
+	github.com/pion/sctp v1.8.35 // indirect
+	github.com/pion/sdp/v3 v3.0.9 // indirect
+	github.com/pion/srtp/v3 v3.0.4 // indirect
+	github.com/pion/stun/v3 v3.0.0 // indirect
+	github.com/pion/transport/v3 v3.0.7 // indirect
+	github.com/pion/turn/v4 v4.0.0 // indirect
+	github.com/wlynxg/anet v0.0.5 // indirect
+	golang.org/x/crypto v0.29.0 // indirect
+	golang.org/x/net v0.31.0 // indirect
+	golang.org/x/sys v0.27.0 // indirect
+)

experiments/pion-probe/go.sum

@@ -0,0 +1,63 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
+github.com/pion/datachannel v1.5.10 h1:ly0Q26K1i6ZkGf42W7D4hQYR90pZwzFOjTq5AuCKk4o=
+github.com/pion/datachannel v1.5.10/go.mod h1:p/jJfC9arb29W7WrxyKbepTU20CFgyx5oLo8Rs4Py/M=
+github.com/pion/dtls/v3 v3.0.4 h1:44CZekewMzfrn9pmGrj5BNnTMDCFwr+6sLH+cCuLM7U=
+github.com/pion/dtls/v3 v3.0.4/go.mod h1:R373CsjxWqNPf6MEkfdy3aSe9niZvL/JaKlGeFphtMg=
+github.com/pion/ice/v4 v4.0.3 h1:9s5rI1WKzF5DRqhJ+Id8bls/8PzM7mau0mj1WZb4IXE=
+github.com/pion/ice/v4 v4.0.3/go.mod h1:VfHy0beAZ5loDT7BmJ2LtMtC4dbawIkkkejHPRZNB3Y=
+github.com/pion/interceptor v0.1.37 h1:aRA8Zpab/wE7/c0O3fh1PqY0AJI3fCSEM5lRWJVorwI=
+github.com/pion/interceptor v0.1.37/go.mod h1:JzxbJ4umVTlZAf+/utHzNesY8tmRkM2lVmkS82TTj8Y=
+github.com/pion/logging v0.2.2 h1:M9+AIj/+pxNsDfAT64+MAVgJO0rsyLnoJKCqf//DoeY=
+github.com/pion/logging v0.2.2/go.mod h1:k0/tDVsRCX2Mb2ZEmTqNa7CWsQPc+YYCB7Q+5pahoms=
+github.com/pion/mdns/v2 v2.0.7 h1:c9kM8ewCgjslaAmicYMFQIde2H9/lrZpjBkN8VwoVtM=
+github.com/pion/mdns/v2 v2.0.7/go.mod h1:vAdSYNAT0Jy3Ru0zl2YiW3Rm/fJCwIeM0nToenfOJKA=
+github.com/pion/randutil v0.1.0 h1:CFG1UdESneORglEsnimhUjf33Rwjubwj6xfiOXBa3mA=
+github.com/pion/randutil v0.1.0/go.mod h1:XcJrSMMbbMRhASFVOlj/5hQial/Y8oH/HVo7TBZq+j8=
+github.com/pion/rtcp v1.2.15 h1:LZQi2JbdipLOj4eBjK4wlVoQWfrZbh3Q6eHtWtJBZBo=
+github.com/pion/rtcp v1.2.15/go.mod h1:jlGuAjHMEXwMUHK78RgX0UmEJFV4zUKOFHR7OP+D3D0=
+github.com/pion/rtp v1.8.10 h1:puphjdbjPB+L+NFaVuZ5h6bt1g5q4kFIoI+r5q/g0CU=
+github.com/pion/rtp v1.8.10/go.mod h1:8uMBJj32Pa1wwx8Fuv/AsFhn8jsgw+3rUC2PfoBZ8p4=
+github.com/pion/sctp v1.8.35 h1:qwtKvNK1Wc5tHMIYgTDJhfZk7vATGVHhXbUDfHbYwzA=
+github.com/pion/sctp v1.8.35/go.mod h1:EcXP8zCYVTRy3W9xtOF7wJm1L1aXfKRQzaM33SjQlzg=
+github.com/pion/sdp/v3 v3.0.9 h1:pX++dCHoHUwq43kuwf3PyJfHlwIj4hXA7Vrifiq0IJY=
+github.com/pion/sdp/v3 v3.0.9/go.mod h1:B5xmvENq5IXJimIO4zfp6LAe1fD9N+kFv+V/1lOdz8M=
+github.com/pion/srtp/v3 v3.0.4 h1:2Z6vDVxzrX3UHEgrUyIGM4rRouoC7v+NiF1IHtp9B5M=
+github.com/pion/srtp/v3 v3.0.4/go.mod h1:1Jx3FwDoxpRaTh1oRV8A/6G1BnFL+QI82eK4ms8EEJQ=
+github.com/pion/stun/v3 v3.0.0 h1:4h1gwhWLWuZWOJIJR9s2ferRO+W3zA/b6ijOI6mKzUw=
+github.com/pion/stun/v3 v3.0.0/go.mod h1:HvCN8txt8mwi4FBvS3EmDghW6aQJ24T+y+1TKjB5jyU=
+github.com/pion/transport/v3 v3.0.7 h1:iRbMH05BzSNwhILHoBoAPxoB9xQgOaJk+591KC9P1o0=
+github.com/pion/transport/v3 v3.0.7/go.mod h1:YleKiTZ4vqNxVwh77Z0zytYi7rXHl7j6uPLGhhz9rwo=
+github.com/pion/turn/v4 v4.0.0 h1:qxplo3Rxa9Yg1xXDxxH8xaqcyGUtbHYw4QSCvmFWvhM=
+github.com/pion/turn/v4 v4.0.0/go.mod h1:MuPDkm15nYSklKpN8vWJ9W2M0PlyQZqYt1McGuxG7mA=
+github.com/pion/webrtc/v4 v4.0.7 h1:aeq78uVnFZd2umXW0O9A2VFQYuS7+BZxWetQvSp2jPo=
+github.com/pion/webrtc/v4 v4.0.7/go.mod h1:oFVBBVSHU3vAEwSgnk3BuKCwAUwpDwQhko1EDwyZWbU=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/objx v0.4.0/go.mod h1:YvHI0jy2hoMjB+UWwv71VJQ9isScKT/TqJzVSSt89Yw=
+github.com/stretchr/objx v0.5.0/go.mod h1:Yh+to48EsGEfYuaHDzXPcE3xhTkx73EhmCGUpEOglKo=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.7.1/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
+github.com/stretchr/testify v1.8.0/go.mod h1:yNjHg4UonilssWZ8iaSj1OCr/vHnekPRkoO+kdMU+MU=
+github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
+github.com/stretchr/testify v1.9.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+github.com/wlynxg/anet v0.0.5 h1:J3VJGi1gvo0JwZ/P1/Yc/8p63SoW98B5dHkYDmpgvvU=
+github.com/wlynxg/anet v0.0.5/go.mod h1:eay5PRQr7fIVAMbTbchTnO9gG65Hg/uYGdc7mguHxoA=
+golang.org/x/crypto v0.29.0 h1:L5SG1JTTXupVV3n6sUqMTeWbjAyfPwoda2DLX8J8FrQ=
+golang.org/x/crypto v0.29.0/go.mod h1:+F4F4N5hv6v38hfeYwTdx20oUvLLc+QfrE9Ax9HtgRg=
+golang.org/x/net v0.31.0 h1:68CPQngjLL0r2AlUKiSxtQFKvzRVbnzLwMUn5SzcLHo=
+golang.org/x/net v0.31.0/go.mod h1:P4fl1q7dY2hnZFxEk4pPSkDHF+QqjitcnDjUQyMM+pM=
+golang.org/x/sys v0.27.0 h1:wBqf8DvsY9Y/2P8gAfPDEYNuS30J4lPHJxXSb/nJZ+s=
+golang.org/x/sys v0.27.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=