VAPI-3991: implement the Bandwidth StartStream source and wire /bw/stream

[mramasubramanian-bw]

Summary

The Media Streams bridge spoke Twilio's protocol to the customer's bot, but the Bandwidth side was only an interface. Nothing in src/ implemented BwStreamSource, and the server never wired a StartStream destination to the bridge, so a translated Connect/Stream opened a Bandwidth stream to a destination that could not relay anything.

This PR implements Bandwidth's side of the bridge and routes StartStream to it. All four ticket items are done: a live end-to-end call passed on 2026-09-25 (see Live verification), so the README rows for Connect/Stream and the bridge now read Live.

Changes

src/streams/bw-source.ts (new): BwWebSocketSource speaks Bandwidth's StartStream WebSocket protocol.

• start: parses metadata (accountId, callId, streamId, streamName, tracks) and streamParams. waitForStart() gives the server a timeout.
• media: relays the inbound (caller) track. Outbound-track frames and non-string payloads are ignored. Frames that arrive before release() are buffered (bounded to 10 s), so caller audio spoken while the bot's socket is still opening is delivered in order rather than dropped.
• stop: emitted exactly once, on a stop event or socket close.
• sendMedia becomes playAudio with audio/pcmu, flush becomes clear.
• No dtmf: Bandwidth delivers digits via BXML Gather webhooks, not the media socket.

src/server/app.ts

• The translator rewrites a Twilio <Stream url> to wss://<PUBLIC_BASE_URL>/bw/stream?dest=<bot url> (ws:// for an http base in local dev).
• The HTTP upgrade is taken off Fastify's underlying server and handed to ws. The upgrade must carry the same Basic-auth credentials as the /bw/* webhooks (401), dest is required (400), must be ws/wss (400), and passes the egress guard (400). Any other path is 404.
• After Bandwidth's start, a TwilioStreamBridge is built with callSid from callId, accountSid from config, customParameters from streamParams, and the configured playout latency pad. Caller audio is released once the bot's socket is open.
• No start within streamStartTimeoutMs (default 5 s), an unreachable bot, or a bot that accepts TCP but never completes the WebSocket handshake within streamBotConnectTimeoutMs (default 10 s) closes the Bandwidth socket so <StopStream wait="true"> returns and the call's BXML moves on.
• The raw upgrade socket gets an error listener before the egress check awaits DNS, so a reset in that window cannot become an uncaught exception.
• Teardown runs in Fastify's preClose hook, terminating bridges and any upgraded socket that has not sent start yet, so app.close() does not wait on Bandwidth.

src/streams/bridge.ts: new connectTimeoutMs (ws handshakeTimeout, default 10 s) so ready() rejects on a black-hole bot. When the bot closes its socket, the Bandwidth source is closed. On Twilio that ends <Connect> and TwiML resumes. Here it ends the StartStream so BXML resumes likewise.

src/translator/translate.ts: destinationUsername / destinationPassword are stamped on StartStream alongside the existing callback credentials. Bandwidth presents them as the Authorization header on the upgrade.

src/twilio/egress-guard.ts: assertPublicUrl takes a schemes option so the stream route can require ws/wss.

src/server/capture.ts: with TRANSLATOR_CAPTURE_DIR set, raw Bandwidth frames are appended to <dir>/streams/<hash>.jsonl (start, first 10 media, stop). Same hashed-filename and private-mode guardrails as the TwiML capture; the key is a per-connection UUID, never Bandwidth input. The per-stream tally is dropped when the stop frame is captured.

src/server/index.ts: optional STREAM_PLAYOUT_LATENCY_PAD_MS, STREAM_START_TIMEOUT_MS, STREAM_BOT_CONNECT_TIMEOUT_MS.

Fixture

test/fixtures/bandwidth/stream-frames.json. The start.metadata block is the real event recorded on a live call on 2026-09-17, ids redacted. streamParams, media, and stop follow the documented shapes, with the media payload being 20 ms of synthetic PCMU silence. The live call below confirmed these shapes field for field. The frames it captured are deliberately not checked in: they came from a personal line and this repository is public. The _meta block says so and how to refresh from a shared test account.

Verification

• npm run typecheck && npx vitest run: 46 files, 363 passed, 6 skipped. The four WebSocket test files were run five times in a row with no flakes.
• test/streams-bw-source.test.ts: parsing, buffering and release, track filtering, the buffer cap, stop-once, playAudio/clear, onFrame.
• test/server-stream.test.ts: a fake Bandwidth client drives the listening Fastify server to a fake Twilio bot. Both directions end to end, buffered audio order, bot hangup, unreachable bot, and black-hole bot (TCP accepted, no handshake) ending the stream, start timeout, app.close() with a pre-start socket, all four upgrade rejections, the URL rewrite with destination credentials, and frame capture including the 10-frame cap.
• test/translate-callback-auth.test.ts: the new StartStream stamping.

Known limitation, pre-existing

assertPublicUrl resolves dest at upgrade time and the bridge re-resolves when it connects, so a DNS-controlled host could pass the check and rebind to an internal address. The HTTP egress path in src/twilio/egress.ts has the identical check-then-connect pattern, so this is consistent rather than new. A fix (pin the resolved address, or re-check in a lookup hook on the outbound socket) should cover both paths in one follow-up.

Live verification

A real inbound call on 2026-09-25 ran through the translator behind an ngrok tunnel, with TRANSLATOR_CAPTURE_DIR set and a Twilio-protocol echo bot as the customer's bot. Bandwidth fetched the TwiML through /bw/initiate, opened its StartStream WebSocket to /bw/stream (upgrade 101 with the destination credentials), and the bridge relayed it. The caller heard the bot's one-second tone and then their own voice echoed back.

Check	Result
Caller audio to bot	878 frames over 17.6 s
Bot audio to caller	853 frames, audible on the phone
<StreamParam> to customParameters	both values delivered
Mark held for playout (VAPI-3990)	greeting mark returned after 999 ms, echo marks 40 to 51 ms
Stop propagation	bot received stop when the call ended
Captured frames vs fixture	same fields, nesting, and formats; Bandwidth orders eventType last

The first attempt returned 401 on /bw/initiate because the Voice application had no callback credentials configured. Setting them to WEBHOOK_USER / WEBHOOK_PASSWORD fixed it, which is the behaviour AGENTS.md Phase 3 already documents.

Docs

AGENTS.md describes the route, auth, capture, the tunnel requirement for WebSocket upgrades, and the optional latency pad. README.md names the new source in the tree.

Reference: StartStream docs.

[bwappsec]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.