@voxevolv/client 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to `@voxevolv/client` are recorded here.
 
+## 0.3.5 - 2026-09-23
+
+- Preserve global client command order across concurrent context keys and prevent
+  timer updates from being overtaken by screen updates at the LiveKit publish boundary.
+- Add opt-in SDK-owned initial connection recovery with three default attempts,
+  increasing 15/20/25-second readiness budgets, bounded delays, and a 65-second
+  overall startup deadline.
+- Renew the same session's room token between startup attempts while keeping
+  intermediate failures nonterminal.
+- Add `onStartupAttempt()` progress events for connecting and retrying UI.
+- Stop startup retry on terminal HTTP, session, microphone, and audio errors;
+  preserve one configured credential refresh after `401` and honor explicitly
+  retryable `session.error` events.
+- Preserve caller options across startup attempts, retry transient network
+  failures, and enforce the startup deadline during token renewal.
+- Keep explicit startup cancellation disconnected and deliver command timeouts
+  even when an earlier command is still waiting to publish.
+
+## 0.3.4 - 2026-09-22
+
+- Add a typed `trigger` and safe command correlation fields to every recovery event.
+- Keep the latest 128 content-free diagnostic entries in memory and report them
+  only after a slow operation, rejection, failure, timeout, or reconnect.
+- Send triggered reports through the session-scoped diagnostics endpoint without
+  exposing context text, images, tokens, or request URLs, and never let reporting
+  failures affect the realtime call.
+- Coalesce rate-limited triggers into a trailing report and stop waiting on a
+  diagnostics request after five seconds, so later failure evidence is not lost.
+
 ## 0.3.3 - 2026-09-17
 
 - Add identified, revisioned transcript snapshots with `onTranscriptUpdated()` and `session.transcript`.

package/README.md

@@ -26,7 +26,7 @@ Browsers without a build step can use the versioned bundle after publication:
 ```html
 <script type="module">
   import { RealtimeSession } from
-    "https://cdn.jsdelivr.net/npm/@voxevolv/client@0.3.2/dist/browser/index.js";
+    "https://cdn.jsdelivr.net/npm/@voxevolv/client@0.3.5/dist/browser/index.js";
 </script>
 ```
 
@@ -41,6 +41,7 @@ const session = await RealtimeSession.create({
   // Use the hosted API directly when its lifecycle CORS policy is public.
   // A same-origin lifecycle proxy remains supported.
   apiBase: "https://YOUR_VOXEVOLV_HOST/v1",
+  startupRetry: true,
   autoRejoin: true,
   tools: {
     present_attachment: (arguments_) => presentAttachment(arguments_),
@@ -64,6 +65,7 @@ play remote audio:
 ```ts
 const session = new RealtimeSession(credentials, {
   connect: { apiBase: "https://YOUR_VOXEVOLV_HOST/v1" },
+  startupRetry: true,
   autoRejoin: true,
 });
 await session.connect({ microphone: true });
@@ -125,9 +127,64 @@ Applications that intentionally run without agent audio can opt out:
 await session.connect({ waitForRemoteAudio: false });
 ```
 
+## Initial connection retries
+
+Set `startupRetry: true` to let the SDK retry a session that has not connected
+successfully yet. The default policy makes three total attempts with 15, 20,
+and 25-second readiness budgets, waits one second before attempt two and three
+seconds before attempt three, and enforces a 65-second overall deadline. The
+overall deadline also includes room connection, token renewal, microphone
+publication, the client hello, and remote-audio readiness.
+
+Attempt one uses the room token returned at session creation. Later attempts
+obtain a fresh room token for the same VoxEvolv session ID. Intermediate
+failures remain nonterminal; `connect()` rejects and the session enters
+`failed` only when the attempts are exhausted, the overall deadline expires,
+or a terminal error occurs.
+
+```ts
+const session = await RealtimeSession.create({
+  endpoint: "/api/voice-session",
+  apiBase: "https://YOUR_VOXEVOLV_HOST/v1",
+  startupRetry: true,
+  autoRejoin: true,
+});
+
+session.onStartupAttempt(({ status, attempt, maxAttempts, error }) => {
+  if (status === "started" && attempt > 1) {
+    renderConnectionStatus(`Retrying connection (${attempt}/${maxAttempts})…`);
+  }
+  if (status === "failed") recordStartupFailure(attempt, error);
+});
+
+await session.connect();
+```
+
+Custom policies use explicit attempts. `delayBeforeMs` is the wait before that
+attempt. When startup retry is enabled, each attempt's `readyTimeoutMs` replaces
+the single timeout supplied through `connect()` or the constructor defaults.
+
+```ts
+startupRetry: {
+  attempts: [
+    { readyTimeoutMs: 15_000 },
+    { delayBeforeMs: 1_000, readyTimeoutMs: 20_000 },
+    { delayBeforeMs: 3_000, readyTimeoutMs: 25_000 },
+  ],
+  timeoutMs: 65_000,
+}
+```
+
+The SDK does not retry invalid audio configuration, microphone permission or
+device errors, non-retryable `session.error` events, or non-transient HTTP 4xx
+responses such as `401`, `403`, and `409 Session has ended`. A configured
+`refreshCredentials` callback still gets one opportunity to replace expired
+credentials after a `401`. A `session.error` explicitly marked
+`retryable: true` may advance to the next startup attempt.
+
 ## Recovery, rejoin, and connection quality
 
-With `@voxevolv/client@0.3.2`, set `autoRejoin: true` to let the SDK recover
+With `@voxevolv/client@0.3.2` or newer, set `autoRejoin: true` to let the SDK recover
 when an agent leaves, its worker changes, a context command times out, or LiveKit
 exhausts its transport reconnect. Automatic recovery runs only after the session has
 connected successfully, never after an explicit `disconnect()`, `end()`, or
@@ -158,9 +215,9 @@ or replayed during recovery because repeating them could duplicate input. Update
 already in flight may have reached the server even if their acknowledgment was lost.
 
 Keep the existing `RealtimeSession` instance during recovery, register tools on
-that instance, and use `onStateChange` / `onRecovery` for UI. Avoid application
-retry loops that create new sessions. Older clients remain API-compatible but
-need the SDK upgrade to gain agent-loss detection and context restoration.
+that instance, and use `onStateChange`, `onStartupAttempt`, and `onRecovery` for
+UI. Avoid application retry loops that create new sessions. Older clients remain
+API-compatible but need the SDK upgrade to gain these recovery behaviors.
 
 ```ts
 session.onStateChange((state) => {
@@ -169,8 +226,17 @@ session.onStateChange((state) => {
   renderConnectionState(state);
 });
 
-session.onRecovery(({ status, strategy, attempt, error }) => {
-  recordRecovery({ status, strategy, attempt, error });
+session.onRecovery(({ status, strategy, attempt, trigger, messageId, contextKey, timeoutMs, error }) => {
+  recordRecovery({
+    status,
+    strategy,
+    attempt,
+    trigger,
+    messageId,
+    contextKey,
+    timeoutMs,
+    error,
+  });
 });
 
 session.onConnectionQuality((quality) => {
@@ -182,6 +248,17 @@ session.onConnectionQuality((quality) => {
 `waitForState(states, timeoutMs, { signal })` is available for advanced flows
 that need to await a bounded set of lifecycle states.
 
+In version 0.3.4, every recovery event includes a typed `trigger`, such as
+`context_command_timeout`, `livekit_disconnected`, `agent_disconnected`, or
+`worker_replaced`. Context timeouts also include the safe `messageId`,
+`contextKey`, and `timeoutMs` correlation fields. The SDK keeps the latest 128
+content-free transport and command entries in memory. It sends a throttled,
+best-effort report only after a slow operation, rejection, failure, timeout, or
+reconnect. Reports never include context text, screenshots, tokens, or raw URLs,
+and reporting failures never affect the call. A trigger received during the
+throttle window is retained for one trailing report, and each diagnostics request
+stops waiting after five seconds so a stuck endpoint cannot block later evidence.
+
 Manual `rejoin()` remains available. It obtains a fresh room token, disconnects
 any underlying room connection, and reconnects with the original microphone or
 application-owned track choice. A managed microphone that the user muted with
@@ -199,6 +276,7 @@ enabled by default), or a same-origin proxy base that forwards only:
 
 - `POST /sessions/{id}/room-tokens`
 - `GET /sessions/{id}/events`
+- `POST /sessions/{id}/diagnostics`
 - `DELETE /sessions/{id}`
 
 The proxy must forward the browser's `Authorization: Bearer vsa_...` header. It