@voxevolv/client 0.3.7 → 0.3.8

package/CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to `@voxevolv/client` are recorded here.
 
+## 0.3.8 - Unreleased
+
+- Increase the default startup deadline from 65 to 90 seconds, registering about
+  85 seconds for backend recovery and extending the final readiness wait to 50
+  seconds. Custom shorter budgets remain supported; older clients keep their
+  65-second fallback until upgraded.
+
+- Coordinate bounded initial agent recovery through `/sessions/{id}/startup`,
+  preserving the overall startup deadline across browser rejoin attempts.
+  Requires the startup-recovery migration, compatible workers, and control endpoint.
+
+- Deliver bounded diagnostic batches with stable IDs, durable receipts, and capped
+  background retries; report dropped evidence and flush on page hiding/shutdown.
+  Requires the updated backend diagnostic endpoint and migration before rollout.
+
+- Keep healthy calls connected when context commands or transfers time out.
+- Retry the newest silent replacement context in the background with capped
+  exponential backoff, preserving caller deadlines and explicit rejection errors.
+- Complete connection recovery after hello, agent readiness, and audio; restore
+  context independently without replaying speech requests after a delivery timeout.
+- Back off streamed-context retransmission and cancel background delivery on shutdown.
+- Prevent overlapping uploads after transfer timeout, rejoin, or a late acknowledgement,
+  and preserve retained-value identity when retrying restored context.
+
 ## 0.3.7 - 2026-09-25
 
 - Recover a missed session ending from durable events when room-token renewal

package/README.md

@@ -127,15 +127,39 @@ await session.connect({ waitForRemoteAudio: false });
 
 ## Initial connection retries
 
-Startup retries are enabled by default in SDK 0.3.6 for both `new RealtimeSession()`
+Startup retries have been enabled by default since SDK 0.3.6 for both `new RealtimeSession()`
 and `RealtimeSession.create()`. Omit `startupRetry` or pass `true` to retry a
 session that has not connected successfully yet. The default policy allows up to
-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
+three total attempts with 15, 20, and 50-second readiness budgets, waits one second
+before attempt two and three seconds before attempt three, and enforces a
+90-second overall deadline in SDK 0.3.8. The overall deadline also includes room
+connection, token renewal, microphone
 publication, the client hello, and remote-audio readiness.
 
+SDK 0.3.8 coordinates initial agent recovery through the session-scoped
+`POST /sessions/{id}/startup` endpoint. Registration is included in the overall
+startup deadline. It reserves 10% of the remaining budget, capped at five seconds,
+and gives the backend at most 85 seconds.
+The request limit is the smaller of that reserve and three seconds; a five-second
+custom startup budget therefore retains about 4.5 seconds on the server.
+Repeated registrations and room-token requests never renew the backend deadline.
+Applications proxying the API must forward this route as well.
+
+The backend inspects stalled startup after ten seconds of candidate presence.
+A failed or expired dispatch can be replaced at most three times, with at least
+ten seconds between attempts. A pending/running dispatch gets a twenty-second
+startup allowance; a recent heartbeat or existing agent prevents replacement.
+The longer window gives three replacements more time to fit; scheduling and
+network delays can still reduce the number of attempts.
+The server also enrolls older SDK clients at session creation and discovers their
+first candidate join through LiveKit polling, without requiring webhooks. Older
+clients retain a 65-second fallback window to match their browser deadline;
+upgrading the SDK enables the longer window.
+Brief browser absence pauses repair until it rejoins the same room. The browser
+still uses the normal SDK startup retry policy, including disconnect/rejoin gaps.
+A dispatch API success means requested, not ready: readiness is recorded separately.
+There is no guaranteed recovery time or guarantee that a healthy worker exists.
+
 Set `startupRetry: false` in the constructor or `create()` options for a single
 startup attempt using the `readyTimeoutMs` supplied through `connect()` or the
 constructor defaults. This does not disable `autoRejoin` after a successful connection.
@@ -172,9 +196,9 @@ startupRetry: {
   attempts: [
     { readyTimeoutMs: 15_000 },
     { delayBeforeMs: 1_000, readyTimeoutMs: 20_000 },
-    { delayBeforeMs: 3_000, readyTimeoutMs: 25_000 },
+    { delayBeforeMs: 3_000, readyTimeoutMs: 50_000 },
   ],
-  timeoutMs: 65_000,
+  timeoutMs: 90_000,
 }
 ```
 
@@ -187,8 +211,8 @@ credentials after a `401`. A `session.error` explicitly marked
 
 ## Recovery, rejoin, and connection quality
 
-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
+Set `autoRejoin: true` to let the SDK recover
+when an agent leaves, its worker changes, or LiveKit
 exhausts its transport reconnect. Automatic recovery runs only after the session has
 connected successfully, never after an explicit `disconnect()`, `end()`, or
 terminal LiveKit removal. It waits for browser connectivity, obtains a fresh
@@ -198,8 +222,9 @@ Automatic rejoin has a default 180-second deadline, including time spent offline
 Use `autoRejoin: { timeoutMs: 180_000 }` to configure it; an explicit `maxAttempts`
 can stop retries earlier. This renews the room connection for the **same session**.
 It never creates a replacement assessment/session. `connected` is reported only
-after the client hello (including tool handlers), agent readiness, remote audio
-(unless opted out), and replacement-context restoration succeed.
+after the client hello (including tool handlers), agent readiness, and remote audio
+(unless opted out) succeed. Replacement context synchronizes in the background;
+its failure cannot prevent a healthy call from reporting connected.
 
 The updated server protects replacement-worker startup with a three-minute
 participant grace period. It restores up to the latest 200 committed transcript
@@ -217,6 +242,24 @@ it restores accepted values with `respond: false`. Append updates are not queued
 or replayed during recovery because repeating them could duplicate input. Updates
 already in flight may have reached the server even if their acknowledgment was lost.
 
+Starting in 0.3.8, context command and transfer timeouts never trigger a rejoin.
+The update promise still rejects at its delivery deadline (20 seconds by default),
+so applications can report the failure or submit a fresh timer value. The SDK
+retains the newest silent replacement value per key for background delivery,
+with delays of roughly 1, 2, 4, then 8 seconds, jittered and capped at 8 seconds.
+New submissions replace queued values without bypassing backoff. Command retries
+within a delivery attempt use the same backoff and message ID. Retries pause during
+connection recovery and stop when the session ends, fails, or disconnects.
+If an upload times out while its LiveKit writer is still running, subsequent
+uploads for that key wait for the writer to settle, including across rejoin.
+The pinned writer API has no public cancellation method; this guard prevents
+stalled transfers from accumulating while audio and other context keys continue.
+Invalid or non-retryable rejected updates are discarded. Append updates and
+`respond: true` updates are not automatically replayed after their deadline:
+an acknowledgement can be lost after the worker has already applied the update
+or requested speech. Restoring a retained value after a real rejoin uses
+`respond: false`. Applications remain responsible for the freshness of timer text.
+
 Keep the existing `RealtimeSession` instance during recovery, register tools on
 that instance, and use `onStateChange`, `onStartupAttempt`, and `onRecovery` for
 UI. Avoid application retry loops that create new sessions. Older clients remain
@@ -251,16 +294,31 @@ 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.
+Every recovery event includes a typed `trigger`, such as `livekit_disconnected`,
+`agent_disconnected`, or `worker_replaced`. Context timeouts are recorded in
+diagnostics with message, context-key, and timeout correlation; they no longer
+emit recovery events. The SDK keeps up to 128 content-free entries in a 64 KiB
+recent-history buffer. Slow operations, rejections, failures, timeouts, recovery,
+page hiding, and session shutdown trigger HTTP diagnostic delivery independently
+of the call transport. Reports never include context text, screenshots, tokens,
+or raw URLs, and reporting failures never affect the call.
+
+Starting in 0.3.8, reports are immutable batches of at most 16 KiB with report IDs,
+SDK-instance IDs, increasing entry sequences, a wall-clock start anchor, and
+monotonic relative timings. The SDK accepts delivery only when the backend returns
+that batch's report ID after saving it. One upload runs at a time, each with a
+five-second deadline (including the receipt body) and `keepalive`. Failed uploads
+retry with exponential backoff and jitter, respecting the server's throttle delay.
+Acknowledged entries are not uploaded again. Pending batches and buffered entries
+expire after five minutes; cumulative `dropped_entries` records overflow, expiry,
+and permanent rejection in subsequent reports. This queue is memory-only: browser
+termination can still lose unsent evidence.
+
+Deploy the backend migration and diagnostic endpoint before this SDK. The endpoint
+continues accepting older SDK reports, saves new batches idempotently, and returns
+`429` with `retry_after_ms` when throttled. Stored reports are retained for seven
+days, with bounded cleanup by the existing control jobs process. Worker diagnostic
+logging is unchanged in this release.
 
 Manual `rejoin()` remains available. It obtains a fresh room token, disconnects
 any underlying room connection, and reconnects with the original microphone or
@@ -280,6 +338,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`
+- `POST /sessions/{id}/startup`
 - `DELETE /sessions/{id}`
 
 The proxy must forward the browser's `Authorization: Bearer vsa_...` header. It