voice-runtime 1.1.0 → 2.0.0

package/README.md

@@ -10,16 +10,23 @@ voice agents with bring-your-own telephony, speech, model, and synthesis provide
 
 New to the package? Start with the [beginner's guide](https://github.com/Kkartik14/TVIC/blob/main/docs/getting-started.md).
 Use the [voice-agent guide](https://github.com/Kkartik14/TVIC/blob/main/docs/building-a-voice-agent.md)
-for application design, [providers](https://github.com/Kkartik14/TVIC/blob/main/docs/providers.md)
-for model setup, and [transports](https://github.com/Kkartik14/TVIC/blob/main/docs/transports.md)
-for browser and phone connections.
+for application design, the [TVIC provider overview](https://github.com/Kkartik14/TVIC/blob/main/README.md#providers)
+for supported adapters, and [transports](https://github.com/Kkartik14/TVIC/blob/main/docs/transports.md)
+for browser and phone connections. Sarvam API details are in its
+[official TTS documentation](https://docs.sarvam.ai/api/api-guides-tutorials/text-to-speech/overview).
 
 ## Status
 
-`voice-runtime@1.0.1` is the public Node.js entry point for the TVIC runtime. It
+The `2.0.0` release follows published `1.2.0` and changes the public
+durable-store contracts. If you maintain custom durable-store or
+idempotency-store adapters, read the [2.0.0 migration guide](https://github.com/Kkartik14/TVIC/blob/main/docs/migrations/2.0.0.md)
+before upgrading.
+
+`voice-runtime@2.0.0` is the public Node.js entry point for the TVIC runtime. It
 supports Node.js 22, 24, and 26, ships both ESM and CommonJS entry points, and is
 server-side only. The main CI compatibility matrix exercises all three supported
-lines.
+lines. Check the installed package version before using APIs documented for a
+newer source checkout.
 
 Browser audio connects to a Node server through the browser-audio transport
 adapter. Browser code does not import this package directly.
@@ -68,7 +75,7 @@ audio endpoint or a phone call for your application.
 import { createVoiceAgent } from "voice-runtime";
 
 const agent = createVoiceAgent({
-  prompt: "You schedule appointments for Dr. Kartik. Be concise and confirm the time.",
+  prompt: "You schedule appointments for a doctor Be concise and confirm the time.",
   providers: {
     telephony: { provider: "web-client-audio" },
     stt: { provider: "deepgram", apiKey: process.env.DEEPGRAM_API_KEY },
@@ -132,8 +139,35 @@ its ID must match the returned handle's `callId`. Replace the provider and
 audio. A preconstructed custom `CallHandle` is also supported when the adapter
 already knows how to correlate its events to the managed session.
 
+## Managed session lifecycle
+
+`agent.start()` returns `complete()`, `stop()`, and `finalSession` alongside
+`sessionId` and `run`. Call `session.complete()` when the caller or host has
+finished sending input. It asks the `CallHandle.endInput()` transport hook to
+half-close input, then resolves with the persisted terminal session. The call
+handle must implement `endInput()` for graceful completion. Call
+`session.stop()` to cancel only that session; cancellation remains distinct
+from normal completion and remote hangup. `finalSession` resolves to the
+persisted terminal result after runtime finalization and transport cleanup.
+Per-session and agent shutdown use a bounded drain. If cleanup exceeds the
+deadline, `stop()` and `finalSession` reject with
+`voice_runtime.shutdown_failed` and `lateCleanupPending`; cleanup can continue
+in the background, so keep its dependencies open while it remains active.
+Start `session.run`—typically by beginning to consume its event stream—before
+calling `session.complete()`. Calling `complete()` before the run starts rejects
+with `voice_runtime.session_not_running`.
+
+The runtime `session.run` promise still reports execution failure or
+cancellation by rejecting. Use `finalSession` when the host needs a persisted
+terminal status regardless of whether the run succeeded. See the
+[API reference](https://github.com/Kkartik14/TVIC/blob/main/docs/api-reference.md)
+and [transport lifecycle guide](https://github.com/Kkartik14/TVIC/blob/main/docs/transports.md)
+for the complete contract.
+
 `agent.stop()` is idempotent. If a session is still running, it cancels and
-drains that session before closing the runtime and its stores.
+drains that session before closing the runtime and its stores. A deadline
+failure rejects shutdown and requires the host to retain any dependencies that
+late cleanup still uses.
 
 Errors on `VoiceEvent` and `MediaEvent` payloads are JSON-safe
 `NormalizedError` values. Check them with `isNormalizedError`; the
@@ -160,20 +194,23 @@ outside the realtime critical path.
 
 Each stage is configured independently. Built-in options currently include:
 
-The complete matrix, catalog dates, official provider links, and live-test
-guidance are in the [provider guide](https://github.com/Kkartik14/TVIC/blob/main/docs/providers.md).
+TVIC's supported provider set is listed in the [repository provider overview](https://github.com/Kkartik14/TVIC/blob/main/README.md#providers).
+For current Sarvam API behavior and voice IDs, use the
+[official Sarvam TTS documentation](https://docs.sarvam.ai/api/api-guides-tutorials/text-to-speech/overview).
 
-- STT: Deepgram, Sarvam, ElevenLabs Scribe, AssemblyAI, and Soniox.
+- STT: Deepgram, Sarvam, Cartesia Ink, ElevenLabs Scribe, AssemblyAI, and Soniox.
 - LLM: Groq Chat Completions (the reference path) and an optional OpenAI Responses adapter.
-- TTS: Cartesia and ElevenLabs.
+- TTS: Cartesia, ElevenLabs (WebSocket, REST, and HTTP stream), and Sarvam Bulbul v3/v4 Flash.
 - Transport: browser audio and inbound Twilio Media Streams.
 
 Maturity is intentionally explicit: Web Client Audio and inbound Twilio Media
-Streams are the stable transport paths in `1.0.1`. The paid STT, LLM,
-and TTS adapters are currently `experimental`. Their deterministic protocol
-coverage passes, but each still needs a credential-gated live-service check
-before release notes can call it stable. The root export `PROVIDER_STABILITY`
-contains the machine-readable labels.
+Streams remain the stable transport paths in `2.0.0`. The paid STT, LLM, and TTS
+adapters are currently `experimental`. `validated` is the intermediate label
+for an exact adapter/model/configuration that has passed the small-scale live
+evidence profile and is reasonable for low-volume use; `stable` additionally
+requires a support matrix, release evidence, ownership, and an upgrade policy.
+The root exports `PROVIDER_STABILITY` and `PROVIDER_STABILITY_LEVELS` contain
+the machine-readable labels.
 
 Pass an explicit `apiKey` or use the documented environment variable. Explicit
 credentials take precedence; missing credentials fail before a live session is
@@ -189,11 +226,15 @@ created.
 | Groq       | `GROQ_API_KEY`       |
 | OpenAI     | `OPENAI_API_KEY`     |
 | Cartesia   | `CARTESIA_API_KEY`   |
+| Sarvam TTS | `SARVAM_API_KEY`     |
 
 STT, LLM, and TTS models are independent settings. TTS voice selection is also
 independent. Built-in TTS can read `CARTESIA_VOICE_ID` or
 `ELEVENLABS_VOICE_ID` for its voice. For complete provider-specific control,
 pass a constructed provider instance instead of a built-in configuration object.
+Sarvam's managed configuration defaults to its WebSocket adapter; set
+`transport: "rest"` or `transport: "http-stream"` on the Sarvam TTS config when
+the downstream use case needs one-shot HTTP delivery.
 Built-in STT and LLM configurations reject models outside the
 dated TVIC catalog unless `allowUnknownModel: true` is explicitly set.
 
@@ -241,7 +282,7 @@ application's responsibility.
 
 Advanced runtime, media, provider, normalized-error, and durable-adapter APIs
 are exported from the package root. There are no advanced subpath imports in
-1.0.1. This lets a developer start with `createVoiceAgent` and later own
+2.0.0. This lets a developer start with `createVoiceAgent` and later own
 the runtime/session/pipeline boundaries without changing package names.
 
 Read the [voice-agent guide](https://github.com/Kkartik14/TVIC/blob/main/docs/building-a-voice-agent.md)