@voxevolv/client 0.3.15 → 0.3.17

package/dist/index.js

@@ -7,7 +7,8 @@ import {
   Room,
   RoomEvent,
   RpcError,
-  Track
+  Track,
+  version as LIVEKIT_VERSION
 } from "./vendor/livekit-client.esm.mjs";
 import {
   createClientMessage,
@@ -23,8 +24,12 @@ import {
 import { ContextDeliveryError, contextRetryDelay, ReplacementContextQueue } from "./context-queue.js";
 import {
   ClientDiagnosticBuffer,
+  diagnosticId,
   DiagnosticDeliveryError
 } from "./diagnostics.js";
+import { observeConnectionTransport } from "./connection-diagnostics.js";
+import { observeRpcTransport } from "./rpc-transport-diagnostics.js";
+import { Presentations } from "./presentations.js";
 import { TranscriptStore } from "./transcripts.js";
 import { TranscriptStore as TranscriptStore2 } from "./transcripts.js";
 import {
@@ -49,7 +54,7 @@ import {
   decodeContextUpdatedPayload,
   decodeRealtimeEvent
 } from "./generated/protocol-codecs.js";
-var SDK_VERSION = "0.3.15";
+var SDK_VERSION = "0.3.17";
 var CLIENT_HELLO_TIMEOUT_MS = 3e4;
 var RECOVERY_BUFFER_STALL_MS = 5e3;
 var RECOVERY_BUFFER_POLL_MS = 500;
@@ -172,9 +177,33 @@ var RealtimeSession = class _RealtimeSession {
   diagnosticLoopTimer;
   diagnosticLoopExpectedAt = 0;
   diagnosticLoopDelayMs;
+  diagnosticLoopHistory = [];
+  diagnosticLastSampleAt = 0;
+  stopRpcDiagnostics;
+  diagnosticEngine;
+  connectionDiagnostics;
+  diagnosticRecoveryId;
+  presentations = new Presentations(
+    (request) => this.room.localParticipant.performRpc(request),
+    () => this.sessionEnded || ["disconnected", "failed"].includes(this.stateValue),
+    () => {
+      this.recordDiagnostic({ operation: "tool_rpc", status: "failed", reason: "presentation_receipt_failed" });
+      this.flushDiagnostics("presentation_receipt_failed");
+    }
+  );
   diagnosticReportTimeoutMs = DIAGNOSTIC_REPORT_TIMEOUT_MS;
   onDiagnosticVisibilityChange = () => {
-    if (globalThis.document?.visibilityState === "hidden") this.flushDiagnostics("page_hidden");
+    const reason = globalThis.document?.visibilityState === "hidden" ? "page_hidden" : "page_visible";
+    this.recordDiagnostic({ operation: "browser_runtime", status: "succeeded", reason });
+    this.flushDiagnostics(reason);
+  };
+  onDiagnosticNetworkChange = (event) => {
+    this.recordDiagnostic({ operation: "browser_runtime", status: "succeeded", reason: `network_${event.type}` });
+    this.flushDiagnostics(`network_${event.type}`);
+  };
+  onDiagnosticLifecycle = (event) => {
+    this.recordDiagnostic({ operation: "browser_runtime", status: "succeeded", reason: event.type });
+    this.flushDiagnostics(`page_${event.type}`);
   };
   constructor(credentials, options = {}) {
     validateSessionCredentials(credentials);
@@ -194,6 +223,9 @@ var RealtimeSession = class _RealtimeSession {
     this.startupRetryOptions = resolveStartupRetryOptions(options.startupRetry);
     this.lifecycleCredentials = options.lifecycleCredentials ?? "same-origin";
     this.room = new Room({ adaptiveStream: true, dynacast: true });
+    this.room.voxevolvObserveEngine = () => {
+      this.startRpcDiagnostics();
+    };
     for (const [name, handler] of Object.entries(options.tools ?? {})) {
       this.registerTool(name, handler);
     }
@@ -213,6 +245,7 @@ var RealtimeSession = class _RealtimeSession {
       this.flushDiagnostics("tool_rpc_worker_request");
       return "{}";
     });
+    this.startRpcDiagnostics();
     this.bindRoomEvents();
   }
   async invokeBrowserTool(invocation) {
@@ -248,17 +281,29 @@ var RealtimeSession = class _RealtimeSession {
         throw new RpcError(1500, "Tool invocation arguments must be an object");
       }
       const arguments_ = payload.arguments;
-      this.notifyListeners(this.toolCallListeners, { name: toolName, callId, arguments: arguments_ });
-      record({ stage: "handler_started" });
-      this.flushDiagnostics("tool_rpc_received");
-      slowTimer = globalThis.setTimeout(() => {
-        record({ stage: "handler_started", reason: "handler_slow" });
-        this.flushDiagnostics("tool_rpc_slow");
-      }, 2e3);
+      const context = { callId };
+      const toolCall = { name: toolName, callId, arguments: arguments_ };
+      const execute = async () => {
+        this.notifyListeners(this.toolCallListeners, toolCall);
+        record({ stage: "handler_started" });
+        this.flushDiagnostics("tool_rpc_received");
+        slowTimer = globalThis.setTimeout(() => {
+          record({ stage: "handler_started", reason: "handler_slow" });
+          this.flushDiagnostics("tool_rpc_slow");
+        }, 2e3);
+        const result = await handler(arguments_, context);
+        return JSON.stringify(result ?? null);
+      };
       let response;
       try {
-        const result = await handler(arguments_, { callId });
-        response = JSON.stringify(result ?? null);
+        if (payload.presentation_id !== void 0) {
+          if (toolName !== "present_attachment" || typeof payload.presentation_id !== "string" || !payload.presentation_id || payload.presentation_id.length > 200) {
+            throw new RpcError(1500, "Invalid presentation identity");
+          }
+          response = await this.presentations.invoke(payload.presentation_id, invocation.callerIdentity, execute);
+        } else {
+          response = await execute();
+        }
       } catch (error) {
         const message = error instanceof Error ? error.message : "Browser tool handler failed";
         throw new RpcError(1500, message, void 0, { cause: error });
@@ -671,6 +716,15 @@ var RealtimeSession = class _RealtimeSession {
     } catch (error) {
       if (signal?.aborted) this.rejectPendingCommands(toError(abortError(signal)));
       this.disconnectMode = recovering ? "rejoin" : "connect_failure";
+      if (!recovering) {
+        this.livekitResumeController?.abort(toError(error));
+        this.livekitResumeController = null;
+        this.failRecovery(toError(error));
+        this.recoveryStartedAt = null;
+        this.diagnosticRecoveryId = void 0;
+        this.reconnectStartedAt = null;
+        this.pendingReconnect = null;
+      }
       try {
         await this.room.disconnect();
       } catch {
@@ -1072,15 +1126,32 @@ var RealtimeSession = class _RealtimeSession {
   setState(state) {
     if (this.stateValue === state) return;
     this.stateValue = state;
+    this.recordDiagnostic({ operation: "browser_runtime", status: "succeeded", reason: `state_${state}` });
     if (state === "connecting" || state === "resuming") {
+      this.startRpcDiagnostics();
       this.startDiagnosticLoopMonitor();
+      globalThis.addEventListener?.("online", this.onDiagnosticNetworkChange);
+      globalThis.addEventListener?.("offline", this.onDiagnosticNetworkChange);
       globalThis.document?.addEventListener?.("visibilitychange", this.onDiagnosticVisibilityChange);
+      globalThis.document?.addEventListener?.("freeze", this.onDiagnosticLifecycle);
+      globalThis.document?.addEventListener?.("resume", this.onDiagnosticLifecycle);
     }
     if (state === "disconnected" || state === "failed") {
       globalThis.clearInterval(this.diagnosticLoopTimer);
       this.diagnosticLoopTimer = void 0;
       this.diagnosticLoopDelayMs = void 0;
+      this.diagnosticLoopHistory = [];
+      this.connectionDiagnostics?.stop();
+      this.connectionDiagnostics = void 0;
+      this.diagnosticRecoveryId = void 0;
+      globalThis.removeEventListener?.("online", this.onDiagnosticNetworkChange);
+      globalThis.removeEventListener?.("offline", this.onDiagnosticNetworkChange);
+      this.stopRpcDiagnostics?.();
+      this.stopRpcDiagnostics = void 0;
+      this.diagnosticEngine = void 0;
       globalThis.document?.removeEventListener?.("visibilitychange", this.onDiagnosticVisibilityChange);
+      globalThis.document?.removeEventListener?.("freeze", this.onDiagnosticLifecycle);
+      globalThis.document?.removeEventListener?.("resume", this.onDiagnosticLifecycle);
       this.flushDiagnostics("session_finished");
       const error = new Error(`Session ${state}`);
       this.contextGeneration += 1;
@@ -1114,12 +1185,23 @@ var RealtimeSession = class _RealtimeSession {
         });
       }
     });
-    this.room.on(RoomEvent.SignalReconnecting, () => this.handleLiveKitReconnecting());
-    this.room.on(RoomEvent.Reconnecting, () => this.handleLiveKitReconnecting());
+    this.room.on(RoomEvent.SignalConnected, () => this.startRpcDiagnostics());
+    this.room.on(RoomEvent.SignalReconnecting, () => this.handleLiveKitReconnecting("signal_reconnecting"));
+    this.room.on(RoomEvent.Reconnecting, () => this.handleLiveKitReconnecting("media_reconnecting"));
     this.room.on(RoomEvent.Reconnected, () => {
+      this.startRpcDiagnostics();
       void this.handleLiveKitReconnected();
     });
     this.room.on(RoomEvent.Disconnected, (reason) => {
+      if (!this.disconnectMode && !this.sessionEnded) {
+        this.recordDiagnostic({
+          operation: "connection_transport",
+          status: "failed",
+          reason: "room_disconnected",
+          disconnect_reason: reason
+        });
+        this.flushDiagnostics("room_disconnected");
+      }
       this.handleLiveKitDisconnected(reason);
     });
     this.room.on(RoomEvent.ConnectionStateChanged, (state) => {
@@ -1199,8 +1281,9 @@ var RealtimeSession = class _RealtimeSession {
       this.notifyListeners(this.listeners, value);
     });
   }
-  handleLiveKitReconnecting() {
+  handleLiveKitReconnecting(trigger = "livekit_reconnecting") {
     if (this.sessionEnded || this.disconnectMode === "intentional" || this.terminalReplayController || ["disconnected", "failed"].includes(this.stateValue)) return;
+    this.recordDiagnostic({ operation: "connection_transport", status: "started", reason: trigger });
     this.agentReady = false;
     if (this.autoRejoinPromise !== null || this.activeRecovery?.strategy === "rejoin" || this.disconnectMode === "rejoin") {
       this.setState("resuming");
@@ -1380,6 +1463,7 @@ var RealtimeSession = class _RealtimeSession {
     this.notifyListeners(this.endedListeners, event);
   }
   beginRecovery(strategy, attempt, details) {
+    this.diagnosticRecoveryId ??= diagnosticId();
     this.recoveryStartedAt ??= Date.now();
     this.activeRecovery = { strategy, attempt, details };
     this.recordDiagnostic({
@@ -1412,6 +1496,7 @@ var RealtimeSession = class _RealtimeSession {
     });
     this.flushDiagnostics("recovery_completed");
     this.recoveryStartedAt = null;
+    this.diagnosticRecoveryId = void 0;
     this.activeRecovery = null;
     this.notifyListeners(this.recoveryListeners, {
       status: "succeeded",
@@ -1519,6 +1604,7 @@ var RealtimeSession = class _RealtimeSession {
     this.livekitResumeController?.abort();
     this.livekitResumeController = null;
     this.recoveryStartedAt = null;
+    this.diagnosticRecoveryId = void 0;
     this.autoRejoinController?.abort();
     this.autoRejoinController = null;
     this.manualRejoinController?.abort();
@@ -1967,30 +2053,68 @@ var RealtimeSession = class _RealtimeSession {
       options
     );
   }
+  startRpcDiagnostics() {
+    const engine = this.room.engine;
+    if (!engine || this.stopRpcDiagnostics && this.diagnosticEngine === engine) return;
+    this.stopRpcDiagnostics?.();
+    this.diagnosticEngine = engine;
+    this.connectionDiagnostics?.stop();
+    this.connectionDiagnostics = observeConnectionTransport(engine, (entry) => {
+      if (this.disconnectMode || this.sessionEnded || ["disconnected", "failed"].includes(this.stateValue)) return;
+      this.recordDiagnostic(entry);
+      this.flushDiagnostics("connection_transport");
+    });
+    this.stopRpcDiagnostics = observeRpcTransport(engine, (entry) => {
+      this.recordDiagnostic(entry);
+      this.flushDiagnostics("tool_rpc_transport");
+    });
+  }
   startDiagnosticLoopMonitor() {
     if (this.diagnosticLoopTimer !== void 0) return;
     this.diagnosticLoopExpectedAt = performance.now() + 1e3;
-    this.diagnosticLoopTimer = globalThis.setInterval(() => {
-      const now = performance.now();
-      this.diagnosticLoopDelayMs = Math.max(0, now - this.diagnosticLoopExpectedAt);
-      this.diagnosticLoopExpectedAt = now + 1e3;
-    }, 1e3);
+    this.diagnosticLastSampleAt = performance.now();
+    this.diagnosticLoopTimer = globalThis.setInterval(() => this.sampleDiagnosticLoop(performance.now()), 1e3);
     this.diagnosticLoopTimer.unref?.();
   }
+  sampleDiagnosticLoop(now) {
+    const delay = Math.max(0, now - this.diagnosticLoopExpectedAt);
+    this.diagnosticLoopDelayMs = delay;
+    this.diagnosticLoopExpectedAt = now + 1e3;
+    this.diagnosticLoopHistory.push({ at: now, delay });
+    this.diagnosticLoopHistory = this.diagnosticLoopHistory.filter((sample) => now - sample.at < 3e4).slice(-30);
+    if (delay >= 100 || now - this.diagnosticLastSampleAt >= 1e4) {
+      this.diagnosticLastSampleAt = now;
+      this.recordDiagnostic({ operation: "browser_runtime", status: "succeeded", reason: "timer_sample" });
+      if (delay >= 1e3) this.flushDiagnostics("browser_stall");
+    }
+  }
   recordDiagnostic(entry) {
+    if (entry.operation === "connection_transport") {
+      this.diagnosticRecoveryId ??= diagnosticId();
+    }
     const snapshot = {
       ...entry,
+      recovery_id: this.diagnosticRecoveryId,
+      connection_id: entry.connection_id ?? this.connectionId,
+      participant_sid: this.room.localParticipant.sid || void 0,
+      livekit_version: LIVEKIT_VERSION,
+      browser_online: globalThis.navigator?.onLine,
       connection_state: this.stateValue,
-      buffered_bytes: this.reliableDataChannelBufferedBytes()
+      buffered_bytes: entry.buffered_bytes ?? this.reliableDataChannelBufferedBytes()
     };
-    if (entry.operation === "tool_rpc" || entry.operation === "connection_recovery") {
+    if (["connection_transport", "connection_recovery"].includes(entry.operation)) {
+      snapshot.transport_history ??= this.connectionDiagnostics?.snapshotHistory();
+    }
+    if (["tool_rpc", "rpc_transport", "browser_runtime", "connection_recovery", "connection_transport"].includes(entry.operation)) {
       snapshot.page_visibility = globalThis.document?.visibilityState;
       snapshot.active_context_transfers = this.activeContextTransfers;
       snapshot.active_context_bytes = this.activeContextBytes;
       if (this.diagnosticLoopTimer !== void 0) {
-        snapshot.event_loop_delay_ms = Math.max(
-          this.diagnosticLoopDelayMs ?? 0,
-          performance.now() - this.diagnosticLoopExpectedAt
+        const now = performance.now();
+        snapshot.event_loop_delay_ms = Math.max(this.diagnosticLoopDelayMs ?? 0, now - this.diagnosticLoopExpectedAt);
+        snapshot.event_loop_delay_max_ms = Math.max(
+          snapshot.event_loop_delay_ms,
+          ...this.diagnosticLoopHistory.filter((sample) => now - sample.at < 3e4).map((sample) => sample.delay)
         );
       }
     }