@memberjunction/server 6.2.0-edge.2 → 6.2.0-edge.4

package/src/resolvers/RealtimeBridgeResolver.ts

@@ -1,15 +1,30 @@
 import { Resolver, Mutation, Query, Arg, Ctx, ObjectType, InputType, Field } from 'type-graphql';
 import { randomUUID } from 'crypto';
-import { LogError, LogStatusEx, UserInfo, IMetadataProvider } from '@memberjunction/core';
-import { LiveKitTokenService, LiveKitAgentRoomCoordinator, LiveKitEgressService } from '@memberjunction/livekit-room-server';
+import { LogError, LogStatusEx, UserInfo, IMetadataProvider, RunView } from '@memberjunction/core';
+import { EscapeSQLString } from '@memberjunction/global';
+import type { TurnAddressingMode } from '@memberjunction/ai-bridge-base';
+import {
+  LiveKitTokenService,
+  LiveKitAgentRoomCoordinator,
+  LiveKitEgressService,
+  LiveKitParticipantService,
+  LiveKitUserIdentity,
+  RoomHandoffEngine,
+  type AgentRoomHostOptions,
+  type AgentRoomSession,
+  type ParticipantUpdateResult,
+  type StartAgentRoomSessionParams,
+} from '@memberjunction/livekit-room-server';
 import { AppContext } from '../types.js';
 import { ResolverBase } from '../generic/ResolverBase.js';
 import { GetReadWriteProvider } from '../util.js';
-import { CreateBridgeRealtimeSession, FinalizeBridgeCoAgentRuns, GetRealtimeModelVoices, CreateBridgeRoomTranscriptSink, RealtimeTurnModeratorDecision } from '@memberjunction/ai-agents';
+import { CreateBridgeRealtimeSession, FinalizeBridgeCoAgentRuns, GetRealtimeModelVoices, CreateBridgeRoomTranscriptSink, RealtimeTurnModeratorDecision, GetBridgeRealtimeRuntime } from '@memberjunction/ai-agents';
 import { AIBridgeEngine } from '@memberjunction/ai-bridge-server';
 import { SessionManager } from '../agentSessions/SessionManager.js';
 import { NotificationEngine } from '@memberjunction/notifications';
 import { RegisterMeetingRecordingFile, CorrelateRecordingStart } from './meetingRecordingRegistration.js';
+import { WriteAgentVisionConsentAudit } from './agentVisionConsentAudit.js';
+import { RoomAuthorizationService, type RoomAuthorizationResult } from '@memberjunction/livekit-room-server';
 
 /**
  * Binds the agent realtime-session factory onto the LiveKit room coordinator's model-session creation seam.
@@ -21,6 +36,37 @@ import { RegisterMeetingRecordingFile, CorrelateRecordingStart } from './meeting
  */
 LiveKitAgentRoomCoordinator.Instance.SetSessionFactory(CreateBridgeRealtimeSession);
 
+/**
+ * Binds the turn-taking tool handler seam (same module-load rationale as the factory above). A full-duplex model
+ * in a shared room calls `i_am_addressed` / `yield_turn`; the bridge engine owns what those mean, and this installs
+ * the engine's handler as the model session runtime's local tool handler (`@memberjunction/ai-agents`).
+ */
+LiveKitAgentRoomCoordinator.Instance.SetTurnToolBinder((session, handler) => {
+  const runtime = GetBridgeRealtimeRuntime(session);
+  if (!runtime) {
+    LogError('[RealtimeBridge] the model session has no bridge runtime; i_am_addressed / yield_turn will not execute for it.');
+    return;
+  }
+  runtime.SetLocalToolHandler(handler);
+});
+
+/**
+ * Binds whether an agent watches meetings (same module-load rationale as the factory above). The coordinator asks per
+ * model session; the answer is the agent's `realtime.video.watchMeetings` setting, which the session runtime read from
+ * its effective configuration (`@memberjunction/ai-agents`). The coordinator also requires a model that takes video.
+ */
+LiveKitAgentRoomCoordinator.Instance.SetAgentVisionResolver((session) => GetBridgeRealtimeRuntime(session)?.WatchesMeetingVideo === true);
+
+/**
+ * Binds how a failed agent start is recorded on the agent's co-agent run (same module-load rationale as the factory
+ * above). The coordinator closes the model session of a start that fails before the bridge engine takes it; that close
+ * alone finalizes the run as Completed, so the coordinator first has the session's runtime finalize it as Failed, with the
+ * start's error.
+ */
+LiveKitAgentRoomCoordinator.Instance.SetFailedStartRecorder(async (session, error) => {
+  await GetBridgeRealtimeRuntime(session)?.Finalize(false, error);
+});
+
 /**
  * Binds the co-agent run finalizer onto the bridge engine (same module-load rationale as the factory above).
  * Lets the engine finalize a session's dangling co-agent observability run when it reaps a bridge WITHOUT a
@@ -127,6 +173,35 @@ export class StartLiveKitAgentRoomSessionInput {
 
   @Field(() => String, { nullable: true })
   TurnMode?: string;
+
+  /**
+   * Start the agent able to bring someone into this room: a person (who is offered the conversation and may accept), a
+   * phone number, or another agent. Opt-in, and honoured only when this server has the handoff collaborators configured
+   * (the LiveKit SIP extension); otherwise the agent starts as it always did.
+   */
+  @Field(() => Boolean, { nullable: true })
+  EnableHandoff?: boolean;
+
+  /**
+   * How this agent decides it was addressed: `Auto` (default — the model's own judgement when it is full-duplex,
+   * name matching otherwise), `ModelSide`, or `Regex`.
+   */
+  @Field(() => String, { nullable: true })
+  TurnAddressing?: string;
+}
+
+/** The live turn-taking state of a room (floor holder, human speaking, hand-off, loop cap, recent events, seated agents). */
+@ObjectType()
+export class LiveKitRoomTurnStateResult {
+  @Field(() => Boolean)
+  Success: boolean;
+
+  @Field(() => String, { nullable: true })
+  ErrorMessage?: string;
+
+  /** JSON of the room's `RoomTurnSnapshot`; `null` when the room holds no agents. Parsed by the typed client. */
+  @Field(() => String, { nullable: true })
+  StateJSON?: string;
 }
 
 @ObjectType()
@@ -181,7 +256,30 @@ export class LiveKitRecordingResult {
   RecordingFileID?: string;
 }
 
-/** A selectable provider-native voice for the dev voice picker. */
+/** A person's choice of whether agents may see their camera and shared screen in a room. */
+@InputType()
+export class SetLiveKitAgentVisionInput {
+  @Field(() => String)
+  RoomName: string;
+
+  /** `true` to let agents see, `false` to stop. */
+  @Field(() => Boolean)
+  Allow: boolean;
+}
+
+@ObjectType()
+export class LiveKitAgentVisionResult {
+  @Field(() => Boolean)
+  Success: boolean;
+
+  @Field(() => String, { nullable: true })
+  ErrorMessage?: string;
+}
+
+/**
+ * A selectable provider-native voice for the dev voice picker: one per persona, or one per voice only the driver declares.
+ * Two personas can share an `ID` (a voice, and the same voice with a face); `PersonaID` tells them apart.
+ */
 @ObjectType()
 export class RealtimeVoiceOptionResult {
   @Field(() => String)
@@ -189,6 +287,22 @@ export class RealtimeVoiceOptionResult {
 
   @Field(() => String)
   Name: string;
+
+  /** The persona this voice belongs to (`MJ: AI Personas.ID`). Null for a voice only the driver declares. */
+  @Field(() => String, { nullable: true })
+  PersonaID?: string;
+
+  /**
+   * The avatar that comes with this voice: the `APIName` of its persona's preset Video binding on the model's vendor,
+   * which is what `realtime.video.avatarId` takes. Null for a voice without one, and for every voice only the driver
+   * declares.
+   */
+  @Field(() => String, { nullable: true })
+  AvatarID?: string;
+
+  /** The persona's preview image URL, or null when it has none. */
+  @Field(() => String, { nullable: true })
+  PreviewImageURL?: string;
 }
 
 /** An active Realtime model with the voices its driver supports — feeds the dev model/voice picker. */
@@ -231,6 +345,11 @@ export class RealtimeBridgeResolver extends ResolverBase {
       if (!user) {
         return failure('Unable to determine current user.');
       }
+      const provider = GetReadWriteProvider(context.providers) as IMetadataProvider;
+      const auth = await RoomAuthorizationService.Instance.AuthorizeRoomAccess(input.RoomName, user, provider);
+      if (!auth.Authorized) {
+        return failure(auth.Reason ?? 'Unauthorized room access.');
+      }
       const tokenService = new LiveKitTokenService();
       const minted = await tokenService.MintClientToken(input.RoomName, this.participantIdentity(user), input.DisplayName ?? user.Name ?? user.Email);
       return { Success: true, ...minted };
@@ -243,7 +362,9 @@ export class RealtimeBridgeResolver extends ResolverBase {
 
   /**
    * Starts (or reuses) an agent's presence in a LiveKit room and returns a client token so the calling
-   * user can immediately join the same room.
+   * user can immediately join the same room. The token is minted before anything starts, so a start that can't give the
+   * user one fails with nothing started. When no `AgentSessionID` is passed, an agent session is created for the
+   * agent; if the agent then fails to start, that session is closed (`Error`) before the failure is returned.
    */
   @Mutation(() => LiveKitAgentRoomSessionResult)
   async StartLiveKitAgentRoomSession(
@@ -264,14 +385,44 @@ export class RealtimeBridgeResolver extends ResolverBase {
       if (!user) {
         return failure('Unable to determine current user.');
       }
-      const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+      const provider = GetReadWriteProvider(context.providers) as IMetadataProvider;
       const roomName = input.RoomName?.trim() || `mj-${randomUUID()}`;
 
+      if (input.RoomName?.trim()) {
+        const auth = await RoomAuthorizationService.Instance.AuthorizeRoomAccess(roomName, user, provider);
+        if (!auth.Authorized) {
+          return failure(auth.Reason ?? 'Unauthorized room access.', roomName);
+        }
+      }
+
+      // The user's token first: a start that can't let the user into the room fails before anything starts there. Minted
+      // after the agent joined, a failure left the agent in a room the user couldn't enter and gave the UI no bridge id to
+      // stop it by.
+      const clientToken = await new LiveKitTokenService().MintClientToken(roomName, this.participantIdentity(user), user.Name ?? user.Email);
+
+      // Opt-in: an agent that can bring a person, a number or another agent into this room (the same room, so a visitor
+      // is escalated without leaving it). Falls through to the standard start when the server cannot do handoffs.
+      const handoffSessionBridgeID = await this.startWithHandoff(input, roomName, user, provider);
+      if (handoffSessionBridgeID) {
+        return {
+          Success: true,
+          SessionBridgeID: handoffSessionBridgeID,
+          RoomName: roomName,
+          ServerUrl: clientToken.ServerUrl,
+          ClientToken: clientToken.Token,
+          Identity: clientToken.Identity,
+        };
+      }
+
       // Resolve the AIAgentSession the bridge will reference. The bridge row FK-references
       // AIAgentSession(ID), so we must use an EXISTING session — either one the caller supplied, or a
       // freshly-created one. Previously this minted a bare random UUID with no backing row, so the
       // bridge INSERT failed the FK_AIAgentSessionBridge_Session constraint.
       let agentSessionID = input.AgentSessionID?.trim();
+      // A session created here exists for this agent's time in the room alone, so it closes when the agent leaves, however
+      // it leaves, or at once if the agent fails to start (see startAgentInRoom). A session the caller supplied is the
+      // caller's to close.
+      let createdSessionID: string | undefined;
       if (!agentSessionID) {
         if (!input.AgentID?.trim()) {
           return failure('An AgentID is required to start an agent room session.', roomName);
@@ -282,9 +433,10 @@ export class RealtimeBridgeResolver extends ResolverBase {
           provider,
         );
         agentSessionID = createdSession.ID;
+        createdSessionID = createdSession.ID;
       }
 
-      const session = await LiveKitAgentRoomCoordinator.Instance.StartAgentRoomSession({
+      const session = await this.startAgentInRoom(createdSessionID, user, provider, {
         AgentSessionID: agentSessionID,
         RoomName: roomName,
         AgentID: input.AgentID,
@@ -293,13 +445,11 @@ export class RealtimeBridgeResolver extends ResolverBase {
         RealtimeModelID: input.RealtimeModelID,
         RealtimeVoice: input.RealtimeVoice,
         TurnMode: this.normalizeTurnMode(input.TurnMode),
+        TurnAddressing: this.normalizeTurnAddressing(input.TurnAddressing),
         ContextUser: user,
         MetadataProvider: provider,
       });
 
-      const tokenService = new LiveKitTokenService();
-      const clientToken = await tokenService.MintClientToken(roomName, this.participantIdentity(user), user.Name ?? user.Email);
-
       return {
         Success: true,
         SessionBridgeID: session.SessionBridgeID,
@@ -319,6 +469,7 @@ export class RealtimeBridgeResolver extends ResolverBase {
    * Stops one agent's presence in a room (the bot leaves) — the remove half of in-room agent management.
    * Identified by the `SessionBridgeID` returned from {@link StartLiveKitAgentRoomSession}. Returns `true`
    * when the bridge was stopped. Best-effort: a missing/already-stopped bridge or any error resolves `false`.
+   * The agent session the start created for the agent is closed (`Explicit`) before this returns.
    *
    * @param sessionBridgeID The `MJ: AI Agent Session Bridges` row id of the agent to remove.
    */
@@ -332,7 +483,15 @@ export class RealtimeBridgeResolver extends ResolverBase {
       if (!user) {
         return false;
       }
-      const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+      const provider = GetReadWriteProvider(context.providers) as IMetadataProvider;
+      const roomName = LiveKitAgentRoomCoordinator.Instance.GetRoomForBridge(sessionBridgeID);
+      if (roomName) {
+        const auth = await RoomAuthorizationService.Instance.AuthorizeRoomAccess(roomName, user, provider);
+        if (!auth.Authorized) {
+          LogError(`StopLiveKitAgentRoomSession unauthorized: user ${user.ID} cannot access room ${roomName} (${auth.Reason})`);
+          return false;
+        }
+      }
       return await LiveKitAgentRoomCoordinator.Instance.StopAgentRoomSession(sessionBridgeID, 'Explicit', user, provider);
     } catch (error) {
       LogError(`StopLiveKitAgentRoomSession failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -345,6 +504,7 @@ export class RealtimeBridgeResolver extends ResolverBase {
    * coordinator's server-side roster). This is the "End meeting" half of the Zoom-style leave control —
    * usable by any participant, including one who only *joined* the room and never tracked the bridge ids.
    * Returns `true` when the teardown ran (even if the room held zero agents). Best-effort: any error → `false`.
+   * The agent sessions the starts created for the agents are closed (`Explicit`) as each agent leaves.
    *
    * @param roomName The LiveKit room to end.
    */
@@ -358,7 +518,12 @@ export class RealtimeBridgeResolver extends ResolverBase {
       if (!user) {
         return false;
       }
-      const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+      const provider = GetReadWriteProvider(context.providers) as IMetadataProvider;
+      const auth = await RoomAuthorizationService.Instance.AuthorizeRoomAccess(roomName, user, provider);
+      if (!auth.Authorized) {
+        LogError(`EndLiveKitRoom unauthorized: user ${user.ID} cannot access room ${roomName} (${auth.Reason})`);
+        return false;
+      }
       await LiveKitAgentRoomCoordinator.Instance.StopAllAgentsInRoom(roomName, 'Explicit', user, provider);
       return true;
     } catch (error) {
@@ -367,6 +532,37 @@ export class RealtimeBridgeResolver extends ResolverBase {
     }
   }
 
+  /**
+   * A room's live turn-taking state — who holds the floor, whether a person is speaking, any pending hand-off,
+   * the agent-to-agent loop-cap progress, the most recent floor/backchannel/yield events, and who is seated. The
+   * agent test bed polls it. Read-only. `StateJSON` is `null` when no agent is in the room.
+   *
+   * @param roomName The LiveKit room.
+   */
+  @Query(() => LiveKitRoomTurnStateResult)
+  async GetLiveKitRoomTurnState(
+    @Arg('roomName', () => String) roomName: string,
+    @Ctx() context: AppContext = {} as AppContext,
+  ): Promise<LiveKitRoomTurnStateResult> {
+    try {
+      const user = this.GetUserFromPayload(context.userPayload);
+      if (!user) {
+        return { Success: false, ErrorMessage: 'Unable to determine current user.' };
+      }
+      const provider = GetReadWriteProvider(context.providers) as IMetadataProvider;
+      const auth = await RoomAuthorizationService.Instance.AuthorizeRoomAccess(roomName, user, provider);
+      if (!auth.Authorized) {
+        return { Success: false, ErrorMessage: auth.Reason ?? 'Unauthorized room access.' };
+      }
+      const snapshot = LiveKitAgentRoomCoordinator.Instance.GetRoomTurnState(roomName);
+      return { Success: true, StateJSON: snapshot ? JSON.stringify(snapshot) : undefined };
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      LogError(`GetLiveKitRoomTurnState failed: ${msg}`);
+      return { Success: false, ErrorMessage: msg };
+    }
+  }
+
   /**
    * Lists active Realtime models with the voices each driver supports — the source for the dev model/voice
    * picker (gated client-side by the `Realtime: Advanced Session Controls` authorization). Read-only; returns
@@ -381,7 +577,7 @@ export class RealtimeBridgeResolver extends ResolverBase {
       if (!user) {
         return [];
       }
-      const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+      const provider = GetReadWriteProvider(context.providers) as IMetadataProvider;
       return await GetRealtimeModelVoices(user, provider);
     } catch (error) {
       LogError(`GetRealtimeModelVoices failed: ${error instanceof Error ? error.message : String(error)}`);
@@ -411,7 +607,12 @@ export class RealtimeBridgeResolver extends ResolverBase {
       if (!user) {
         return false;
       }
-      const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+      const provider = GetReadWriteProvider(context.providers) as IMetadataProvider;
+      const auth = await RoomAuthorizationService.Instance.AuthorizeRoomAccess(roomName, user, provider);
+      if (!auth.Authorized) {
+        LogError(`InviteUsersToLiveKitRoom unauthorized: user ${user.ID} cannot access room ${roomName} (${auth.Reason})`);
+        return false;
+      }
       await NotificationEngine.Instance.Config(false, user, provider);
 
       const inviter = user.Name?.trim() || user.Email || 'Someone';
@@ -453,11 +654,15 @@ export class RealtimeBridgeResolver extends ResolverBase {
       if (!user) {
         return { Success: false, ErrorMessage: 'Unable to determine current user.', EgressID: '', Status: '' };
       }
+      const provider = GetReadWriteProvider(context.providers) as IMetadataProvider;
+      const auth = await RoomAuthorizationService.Instance.AuthorizeRoomAccess(input.RoomName, user, provider);
+      if (!auth.Authorized) {
+        return { Success: false, ErrorMessage: auth.Reason ?? 'Unauthorized room access.', EgressID: '', Status: '' };
+      }
       const info = await new LiveKitEgressService().StartRoomRecording({ RoomName: input.RoomName, Layout: input.Layout });
 
       // Best-effort: correlate the live recording with the room's Meeting-Room Conversation (if it exists
       // yet) by stamping its EgressID. Never fail the start on this — the stop-flow resolves/creates it.
-      const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
       void CorrelateRecordingStart(input.RoomName, info.EgressID, user, provider);
 
       return { Success: true, EgressID: info.EgressID, Status: info.Status };
@@ -481,8 +686,43 @@ export class RealtimeBridgeResolver extends ResolverBase {
       if (!user) {
         return { Success: false, ErrorMessage: 'Unable to determine current user.', EgressID: egressID, Status: '' };
       }
-      const info = await new LiveKitEgressService().StopRecording(egressID);
-      const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+      const provider = GetReadWriteProvider(context.providers) as IMetadataProvider;
+
+      // Map egress ID to room name: check LiveKit egress service first, fallback to Conversation if available.
+      const egressService = new LiveKitEgressService();
+      let roomName = await egressService.GetRoomForEgress(egressID);
+      if (!roomName && provider) {
+        try {
+          const rv = RunView.FromMetadataProvider(provider);
+          const convResult = await rv.RunView<{ ExternalID: string }>(
+            {
+              EntityName: 'MJ: Conversations',
+              ExtraFilter: `EgressID='${EscapeSQLString(egressID)}' AND (IsArchived IS NULL OR IsArchived=0)`,
+              Fields: ['ExternalID'],
+              OrderBy: '__mj_CreatedAt DESC',
+              MaxRows: 1,
+              ResultType: 'simple',
+            },
+            user,
+          );
+          if (convResult.Success && convResult.Results.length > 0 && convResult.Results[0].ExternalID) {
+            roomName = convResult.Results[0].ExternalID;
+          }
+        } catch (err) {
+          LogError(`StopLiveKitRecording: error looking up Conversation for egress ID '${egressID}'`, undefined, err);
+        }
+      }
+
+      if (roomName) {
+        const auth = await RoomAuthorizationService.Instance.AuthorizeRoomAccess(roomName, user, provider);
+        if (!auth.Authorized) {
+          return { Success: false, ErrorMessage: auth.Reason ?? 'Unauthorized room access.', EgressID: egressID, Status: '' };
+        }
+      } else {
+        return { Success: false, ErrorMessage: `Unable to determine room for egress ID '${egressID}'.`, EgressID: egressID, Status: '' };
+      }
+
+      const info = await egressService.StopRecording(egressID);
 
       // Register the completed egress MP4 as a Files row on the Meeting-Room Conversation. Best-effort:
       // any failure (e.g. storage provider not configured) leaves RecordingFileID unset but still
@@ -504,9 +744,135 @@ export class RealtimeBridgeResolver extends ResolverBase {
     }
   }
 
-  /** Builds a stable, lowercased participant identity from the authenticated user. */
+  /**
+   * Records whether the current user lets agents see their camera and shared screen in a room. The participant is
+   * worked out from the authenticated user, never sent by the client, so a person can only answer for themselves. To
+   * allow, the room must be one they may enter ({@link RoomAuthorizationService}, as for every room mutation). A
+   * withdrawal skips that check: a cancelled meeting or a failed lookup must not keep an agent watching someone who is
+   * still in the room, and the identity is always the caller's own. LiveKit refuses either way when they are not in it. The choice is set as their `mj.agentCanSee` attribute through LiveKit's server SDK (a
+   * participant's token can't change its own attributes) and audited, applied or not.
+   */
+  @Mutation(() => LiveKitAgentVisionResult)
+  async SetLiveKitAgentVision(
+    @Arg('input', () => SetLiveKitAgentVisionInput) input: SetLiveKitAgentVisionInput,
+    @Ctx() context: AppContext = {} as AppContext,
+  ): Promise<LiveKitAgentVisionResult> {
+    try {
+      const user = this.GetUserFromPayload(context.userPayload);
+      if (!user) {
+        return { Success: false, ErrorMessage: 'Unable to determine current user.' };
+      }
+      const provider = GetReadWriteProvider(context.providers) as unknown as IMetadataProvider;
+      const auth: RoomAuthorizationResult = input.Allow
+        ? await RoomAuthorizationService.Instance.AuthorizeRoomAccess(input.RoomName, user, provider)
+        : { Authorized: true };
+      const result: ParticipantUpdateResult = auth.Authorized
+        ? await new LiveKitParticipantService().SetAgentVision(input.RoomName, this.participantIdentity(user), input.Allow)
+        : { Success: false, ErrorMessage: auth.Reason ?? 'Unauthorized room access.' };
+      await WriteAgentVisionConsentAudit(
+        { User: user, RoomName: input.RoomName, Allow: input.Allow, Applied: result.Success, ErrorMessage: result.ErrorMessage },
+        provider,
+      );
+      if (result.Success) {
+        return { Success: true };
+      }
+      return { Success: false, ErrorMessage: result.NotInRoom ? 'You are not in this room.' : result.ErrorMessage };
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      LogError(`SetLiveKitAgentVision failed: ${msg}`);
+      return { Success: false, ErrorMessage: msg };
+    }
+  }
+
+  /**
+   * Starts the agent through the handoff-capable room starter when the caller asked for it and the server can do it.
+   * Returns the bridge id, or `undefined` to mean "use the standard start" (not requested, no starter, no agent named).
+   */
+  private async startWithHandoff(
+    input: StartLiveKitAgentRoomSessionInput,
+    roomName: string,
+    user: UserInfo,
+    provider: IMetadataProvider,
+  ): Promise<string | undefined> {
+    if (!input.EnableHandoff) {
+      return undefined;
+    }
+    const starter = RoomHandoffEngine.Instance.Deps.AgentStarter;
+    const agentID = input.TargetAgentID?.trim() || input.AgentID?.trim();
+    if (!starter || !agentID) {
+      LogError('StartLiveKitAgentRoomSession: handoff was requested but this server has no handoff-capable agent starter; starting the agent without it.');
+      return undefined;
+    }
+    const started = await starter({
+      RoomName: roomName,
+      AgentID: agentID,
+      AgentName: input.AgentName?.trim() ?? '',
+      CallerLabel: user.Name?.trim() || user.Email || 'Web visitor',
+      ContextUser: user,
+      Provider: provider,
+      RealtimeModelID: input.RealtimeModelID,
+      RealtimeVoice: input.RealtimeVoice,
+    });
+    return started.SessionBridgeID;
+  }
+
+  /**
+   * Starts the agent in the room through the coordinator. An agent session created for this agent's time in the room
+   * (`createdSessionID`) is this start's to close: once the agent has joined, through the end-of-session hook from
+   * {@link closeSessionWhenAgentLeaves}; when the start fails, at once, as `Error`, through
+   * {@link SessionManager.CloseSessionForFailedStart}, before the error propagates, since the agent never joined and that
+   * hook never runs (#5308). By then the coordinator has closed any model session the start opened, its co-agent run
+   * finalized as failed. A session the caller supplied gets neither: it is the caller's.
+   */
+  private async startAgentInRoom(
+    createdSessionID: string | undefined,
+    user: UserInfo,
+    provider: IMetadataProvider,
+    params: Omit<StartAgentRoomSessionParams, 'Host'>,
+  ): Promise<AgentRoomSession> {
+    const coordinator = LiveKitAgentRoomCoordinator.Instance;
+    if (!createdSessionID) {
+      return coordinator.StartAgentRoomSession(params);
+    }
+    try {
+      return await coordinator.StartAgentRoomSession({ ...params, Host: this.closeSessionWhenAgentLeaves(createdSessionID, user, provider) });
+    } catch (error) {
+      await this.sessionManager.CloseSessionForFailedStart(createdSessionID, user, provider);
+      throw error;
+    }
+  }
+
+  /**
+   * What the coordinator is given for an agent session created for one agent's time in a room: its end-of-session hook
+   * closes the session once the agent's bridge has ended, whatever ended it (the agent stopped, the meeting ended, everyone
+   * left, the model session lost), through {@link SessionManager.CloseSessionForEndedBridge}. The close runs as the user
+   * who started the agent, whoever stops it: the session is theirs.
+   */
+  private closeSessionWhenAgentLeaves(agentSessionID: string, user: UserInfo, provider: IMetadataProvider): AgentRoomHostOptions {
+    return {
+      OnSessionEnded: async (reason) => {
+        await this.sessionManager.CloseSessionForEndedBridge(agentSessionID, reason, user, provider);
+      },
+    };
+  }
+
+  /** Builds a stable, lowercased participant identity from the authenticated user (shared with the handoff engine, which watches for it). */
   private participantIdentity(user: UserInfo): string {
-    return `user-${user.ID}`.toLowerCase();
+    return LiveKitUserIdentity(user.ID);
+  }
+
+  /** Normalizes an addressing-mode string; unknown/absent leaves the coordinator's default (`Auto`). */
+  private normalizeTurnAddressing(mode?: string): TurnAddressingMode | undefined {
+    switch ((mode ?? '').trim().toLowerCase()) {
+      case 'auto':
+        return 'Auto';
+      case 'modelside':
+        return 'ModelSide';
+      case 'regex':
+        return 'Regex';
+      default:
+        return undefined;
+    }
   }
 
   /** Normalizes a turn-mode string to the bridge's accepted values. */