chore: Align frontend with LexVoice gateway deploy

.env.example

@@ -1,13 +1,17 @@
 # This file is intentionally documentation-only.
 #
 # Integrated LexVoice runs should not configure frontend variables here.
-# Use `../lex-voice/.env` as the single source of truth; `lex-voice/run.sh`
-# injects LiveKit, room-input, input-source, role-device, agent, media, and
-# debug settings into the frontend process when it starts `make start_ui`.
+# Use the LexVoice repository `.env` as the single source of truth; its `run.sh`
+# injects LiveKit, room-input, input-source, role-device, agent, media, and debug
+# settings into the frontend process when it starts `make start_ui`.
 #
 # Only create `agent-starter-react/.env.local` for standalone frontend
 # development where this repository is launched directly with `pnpm dev`.
 # In that case, define only the variables needed for that standalone run.
+
+# For sandbox gateway deployment, see the LexVoice repository's
+# `deploy/liveavatar_gateway/.env.example.gateway` and
+# `deploy/liveavatar_gateway/.env.example.sandbox` reference files.
 #
 # `OBSERVABILITY_ENABLED=1` uses the same unified switch as the backend. When
 # enabled by the LexVoice runtime, browser-side probes publish LiveKit data

.gitignore

@@ -13,6 +13,12 @@
 # testing
 /coverage
 
+# Legacy sandbox gateway artifacts from pre-migration local runs
+/.sandbox-gateway/
+/logs/direct-proxy.log
+/logs/sandbox-gateway*.log
+/logs/sandbox-gateway.pid
+
 # next.js
 /.next/
 /out/

README.md

@@ -57,17 +57,27 @@ Run the following command to automatically clone this template.
 lk app create --template agent-starter-react
 ```
 
-For integrated LexVoice runs, configure `../lex-voice/.env` and start the
-frontend through the LexVoice runtime scripts. `../lex-voice/run.sh` injects
-LiveKit, room-input, input-source, role-device, agent, media, and debug settings
-into this Next.js process.
+For integrated LexVoice runs, configure the LexVoice repository `.env` and start
+the frontend through the LexVoice runtime scripts. The LexVoice repository's
+`run.sh` injects LiveKit, room-input, input-source, role-device, agent, media,
+and debug settings into this Next.js process.
 
 The session lifecycle API keeps start/stop state in memory, so integrated
 deployments should route `/api/session/*` to a single Next.js instance or sticky routing.
 If you replace the custom connection details endpoint, it must echo the requested
 `sessionId` and derive the same room name so dispatch and stop calls coordinate
 with the connected room.
 
+### LiveAvatar Gateway Deployments
+
+Sandbox-backed public deployments are owned by the LexVoice repository. Set
+`LIVEAVATAR_USE_SANDBOX=1` in the LexVoice repository `.env` and configure
+broker, template, warm pool, and `SANDBOX_ENV_*` values in the LexVoice repository's
+`deploy/liveavatar_gateway/.env`.
+
+This frontend repository only runs the Next.js UI. It does not create, release,
+or warm sandbox sessions.
+
 For standalone frontend development, install dependencies and run the dev
 server directly:
 
@@ -78,8 +88,8 @@ pnpm dev
 
 And open http://localhost:3000 in your browser.
 
-You'll also need a LiveKit server and an agent worker. In this workspace, those
-are normally provided by the sibling `../lex-voice` project.
+You'll also need a LiveKit server and an agent worker. In integrated workspaces,
+those are normally provided by the LexVoice project.
 
 ## Configuration
 
@@ -118,7 +128,7 @@ You can update these values in [`app-config.ts`](./app-config.ts) to customize b
 
 #### Environment Variables
 
-Integrated runs should keep runtime variables in `../lex-voice/.env`; this
+Integrated runs should keep runtime variables in the LexVoice repository `.env`; this
 repository's `.env.example` is documentation-only. Only create
 `agent-starter-react/.env.local` for standalone frontend development launched
 directly with `pnpm dev`.
@@ -130,7 +140,7 @@ LIVEKIT_URL=https://your-livekit-server-url
 ```
 
 The frontend defaults to the browser camera/microphone input when no input
-source is provided. Configure `INPUT_SOURCE` only in `../lex-voice/.env` for
+source is provided. Configure `INPUT_SOURCE` only in the LexVoice repository `.env` for
 integrated backend runs. The LiveKit variables above are required for
 standalone voice agent functionality to work with your LiveKit project.
 

app-config.ts

@@ -46,6 +46,7 @@ export interface AppConfig {
 
   // for LiveKit Cloud Sandbox
   sandboxId?: string;
+  voiceSessionId?: string;
   agentName?: string;
   inputSource?: string;
   audioInputDevice?: string;
@@ -227,6 +228,7 @@ export const APP_CONFIG_DEFAULTS: AppConfig = {
 
   // for LiveKit Cloud Sandbox
   sandboxId: undefined,
+  voiceSessionId: undefined,
   agentName: undefined,
   inputSource: undefined,
   audioInputDevice: undefined,

app/api/session/dispatch/route.ts

@@ -1,11 +1,16 @@
 import { NextResponse } from 'next/server';
 import { AgentDispatchClient, RoomServiceClient } from 'livekit-server-sdk';
-import { type ParticipantInfo, ParticipantInfo_Kind } from '@livekit/protocol';
+import { type ParticipantInfo } from '@livekit/protocol';
 import {
   deriveLiveKitRoomName,
   deriveSessionIdFromLiveKitRoomName,
   isValidConnectionRoomId,
 } from '@/lib/connection-room-id';
+import {
+  type AgentParticipantMatchOptions,
+  findAgentParticipantInList,
+  findReusableAgentParticipant as findReusableAgentParticipantInList,
+} from '@/lib/session-dispatch-readiness';
 import { resolveLiveKitHttpUrl } from '@/lib/session-stop';
 import {
   type RoomSessionToken,
@@ -23,10 +28,6 @@ const AGENT_DISPATCH_POLL_MS = readPositiveIntEnv('AGENT_DISPATCH_POLL_MS', 200)
 export const runtime = 'nodejs';
 export const revalidate = 0;
 
-type AgentParticipantMatchOptions = {
-  allowAnonymousLiveKitAgentFallback?: boolean;
-};
-
 class RoomSessionCancelledError extends Error {
   constructor(session: RoomSessionToken) {
     super(
@@ -157,11 +158,15 @@ async function createAgentDispatchWithRetry(
     try {
       throwIfSessionCancelled(session);
 
-      const alreadyJoined = await roomHasAgentParticipant(roomClient, roomName, agentName);
+      const alreadyJoined = await findReusableAgentParticipant(roomClient, roomName, agentName);
       throwIfSessionCancelled(session);
       if (alreadyJoined) {
         markRoomSessionRunning(session);
-        return { attempts, alreadyJoined: true };
+        return {
+          attempts,
+          alreadyJoined: true,
+          agentParticipant: summarizeAgentParticipant(alreadyJoined),
+        };
       }
 
       const dispatch = await dispatchClient.createDispatch(roomName, agentName);
@@ -174,21 +179,28 @@ async function createAgentDispatchWithRetry(
         throw new RoomSessionCancelledError(session);
       }
 
-      if (
-        await waitForAgentParticipant(
-          roomClient,
-          roomName,
-          agentName,
-          remainingDispatchTime(startedAt),
-          session
-        )
-      ) {
+      // A successful LiveKit dispatch often needs multiple seconds before the
+      // agent worker joins the room. Wait for the full remaining session-start
+      // budget here; the retry loop is for API/listParticipants failures, not
+      // for repeatedly recreating a healthy dispatch every retry interval.
+      const agentParticipant = await waitForAgentParticipant(
+        roomClient,
+        roomName,
+        agentName,
+        remainingDispatchTime(startedAt),
+        session
+      );
+      if (agentParticipant) {
         if (isRoomSessionCancelled(session)) {
           await deleteLiveKitRoomQuietly(roomClient, roomName);
           throw new RoomSessionCancelledError(session);
         }
         markRoomSessionRunning(session);
-        return { attempts, dispatchId: dispatch.id };
+        return {
+          attempts,
+          dispatchId: dispatch.id,
+          agentParticipant: summarizeAgentParticipant(agentParticipant),
+        };
       }
 
       lastError = new Error('agent participant did not join before retry');
@@ -231,17 +243,16 @@ async function waitForAgentParticipant(
   maxWaitMs: number,
   session: RoomSessionToken
 ) {
-  const deadline = Date.now() + Math.min(maxWaitMs, AGENT_DISPATCH_RETRY_MS);
+  const deadline = Date.now() + maxWaitMs;
 
   do {
     throwIfSessionCancelled(session);
-    if (
-      await roomHasAgentParticipant(roomClient, roomName, agentName, {
-        allowAnonymousLiveKitAgentFallback: true,
-      })
-    ) {
+    const participant = await findAgentParticipant(roomClient, roomName, agentName, {
+      allowAnonymousLiveKitAgentFallback: true,
+    });
+    if (participant) {
       throwIfSessionCancelled(session);
-      return true;
+      return participant;
     }
 
     const waitMs = Math.min(AGENT_DISPATCH_POLL_MS, deadline - Date.now());
@@ -251,43 +262,38 @@ async function waitForAgentParticipant(
   } while (Date.now() < deadline);
 
   throwIfSessionCancelled(session);
-  return roomHasAgentParticipant(roomClient, roomName, agentName, {
+  return findAgentParticipant(roomClient, roomName, agentName, {
     allowAnonymousLiveKitAgentFallback: true,
   });
 }
 
-async function roomHasAgentParticipant(
+async function findAgentParticipant(
   roomClient: RoomServiceClient,
   roomName: string,
   agentName: string,
   options: AgentParticipantMatchOptions = {}
 ) {
   const participants = await roomClient.listParticipants(roomName);
-  if (participants.some((participant) => isExpectedAgentParticipant(participant, agentName))) {
-    return true;
-  }
-  if (!options.allowAnonymousLiveKitAgentFallback) {
-    return false;
-  }
-
-  // Local LiveKit may omit agent attributes; fresh per-session rooms keep this fallback bounded.
-  const anonymousLiveKitAgents = participants.filter(isAnonymousLiveKitAgentParticipant);
-  return anonymousLiveKitAgents.length === 1;
+  return findAgentParticipantInList(participants, agentName, options);
 }
 
-function isExpectedAgentParticipant(participant: ParticipantInfo, agentName: string) {
-  const attributes = participant.attributes ?? {};
-  return attributes['lk.agent.name'] === agentName || attributes['lk.agent_name'] === agentName;
+async function findReusableAgentParticipant(
+  roomClient: RoomServiceClient,
+  roomName: string,
+  agentName: string
+) {
+  const participants = await roomClient.listParticipants(roomName);
+  return findReusableAgentParticipantInList(participants, agentName);
 }
 
-function isAnonymousLiveKitAgentParticipant(participant: ParticipantInfo) {
-  const attributes = participant.attributes ?? {};
-  return (
-    participant.kind === ParticipantInfo_Kind.AGENT &&
-    participant.identity.startsWith('agent-') &&
-    !attributes['lk.agent.name'] &&
-    !attributes['lk.agent_name']
-  );
+function summarizeAgentParticipant(participant: ParticipantInfo | null) {
+  if (!participant) {
+    return null;
+  }
+
+  return {
+    identity: participant.identity,
+  };
 }
 
 async function deleteDispatchQuietly(

components/app/session-provider.tsx

@@ -14,6 +14,7 @@ const DEFAULT_BROWSER_SOURCE_CLIENT: BrowserSourceClient = {
   videoTrack: null,
   audioPending: false,
   videoPending: false,
+  setAudioDeviceId: async () => {},
   setAudioEnabled: async () => {},
   setVideoEnabled: async () => {},
   start: async () => {},

components/livekit/agent-control-bar/agent-control-bar.tsx

@@ -134,6 +134,20 @@ export function AgentControlBar({
     [browserSourceClient, handleDeviceError]
   );
 
+  const handleAudioDeviceSelect = useCallback(
+    (deviceId: string) => {
+      handleAudioDeviceChange(deviceId);
+      if (!usesBrowserRawAudioInput) {
+        return;
+      }
+
+      void browserSourceClient.setAudioDeviceId(deviceId).catch((error) => {
+        handleDeviceError({ source: Track.Source.Microphone, error });
+      });
+    },
+    [browserSourceClient, handleAudioDeviceChange, handleDeviceError, usesBrowserRawAudioInput]
+  );
+
   const handleRawVideoToggle = useCallback(
     async (enabled: boolean) => {
       try {
@@ -195,7 +209,7 @@ export function AgentControlBar({
                 usesBrowserRawAudioInput ? handleRawMicrophoneToggle : microphoneToggle.toggle
               }
               onMediaDeviceError={handleMicrophoneDeviceSelectError}
-              onActiveDeviceChange={handleAudioDeviceChange}
+              onActiveDeviceChange={handleAudioDeviceSelect}
             />
           )}