feat(sdk): add Telnyx relay voice context and examples

[danielblignaut]

Outcome

Expose agent-owned voice through @trytilde/sdk and @trytilde/sdk-vercel-ai-node, including Telnyx Conversation Relay, OpenAI pipeline/native modes, and a manual browser/phone agent example. Companion API: https://github.com/trytilde/api/pull/277. Public guide: trytilde/docs#37.

Key implementation choices

client.chatkit.audio configures/reads speech settings, starts browser admission, and binds Telnyx routes. The normal endpoint receives validated context.audio / context.telnyx; only the latest user message supplies that context. Generated text/UI history retains interruption and carrier-reported spoken-prefix annotations. Native model transcripts do not invoke a duplicate text callback.

The example uses current SDK names, AI SDK 7, and responseMode: "agentLoop". It registers three agents; the browser tests the two OpenAI modes and Telnyx calls use the relay agent. Managed setup updates an existing customer's application webhook; it does not purchase or assign numbers.

Repository context

• Actual main, remotes, isolated checkout, and full diff reviewed; unrelated work preserved.
• Current custom-provider/direct-workflow SDK changes are integrated.

Validation

• pnpm openbot sdk refresh: generated full contract, built all SDK packages, and passed 327 tests.
• Core SDK and Node-adapter typechecks pass; their focused suites pass 313 tests.
• Manual example typecheck passes; its earlier local startup smoke passed.
• Full application pnpm check / pnpm build not run: this contribution is confined to public SDK packages and an isolated integration example.
• No protobuf or shipped web/Electron behavior changes; no application E2E claim.

The complete schema contains 732 operations. Seven voice operations added, zero existing operations removed, and all 22 wallet/payment operations retained. Generated code was regenerated, never hand-edited. API tests prove the text/control relay through HTTP/Postgres and live OpenAI inference; real Telnyx and browser microphone checks remain manual.

Contracts, state, deployment, and security

• Tenant paths, HTTP compatibility, signed context, credentials, and state impact reviewed.
• Speech settings are portable configuration; keys are secrets; admission tokens are ephemeral; carrier bindings are installation setup.
• No secrets, generated deployment state, root env/SOPS files, or fork configuration included.

No new internal metadata keys. Negative tests reject metadata-derived speech context and stale speech context on a subsequent typed turn. Example registrations remain ignored and use restrictive file permissions.

Configuration ownership

Targets trytilde/dispatch; tracked configuration/ contains only the canonical .gitignore sentinel. Fork initialization rules are not applicable.

Cross-client parity

No shipped client capability changed. The standalone example is a public SDK consumer, not a voice feature in the shared web/Electron client runtime.

Architecture and ADR review

ADR 0030 documents SDK ownership and the relay contract; API ADR 0027 governs speech orchestration. ADR 0038 is preserved. No second speech worker or OpenBot CLI is introduced.

Package documentation and provider contracts

• SDK, Node-adapter, and generated-client READMEs describe the supported surface.
• No application provider-interface changes.
• Manual setup guide covers browser and dedicated Telnyx testing.

Changeset

• .changeset/chatkit-realtime-voice.md covers the two public SDK additions and generated-client update.

PR update record

• docs/updates/155.md records the full current change, Mermaid flow, validation, and critical release actions.

Frontend evidence

Shipped frontend: not applicable. The example typechecks; no actual microphone/carrier test or deployment is claimed.

Known limitations and follow-ups

Direct WebRTC/SIP, ElevenLabs, voice notes, recordings, native endpoint-tool bridging, and browser personal-tool federation are outside this slice. Native mode uses separately configured instructions.

Owner: ChatKit API and SDK Trigger: before enabling production carrier traffic Work: perform a real Telnyx call and browser microphone test with dedicated resources; verify interruption, final transcripts, and call teardown.

Final diff review

• Intentional files only, current generated contract, Conventional Commit title, and draft status.
• no-greptile label retained; Greptile was requested only on API PR 277.
• Final PR checks and feedback inspected after push.

Documentation

Release order: deploy API/migrations → release SDK packages → publish docs PR 37. Source records and companion PR links above are current; the public docs repository now keeps engineering records in source repositories only.