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

package/src/resolvers/RealtimeBridgeResolver.ts

@@ -1,15 +1,24 @@
 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,
+  LiveKitUserIdentity,
+  RoomHandoffEngine,
+} 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 { RoomAuthorizationService } from '@memberjunction/livekit-room-server';
 
 /**
  * Binds the agent realtime-session factory onto the LiveKit room coordinator's model-session creation seam.
@@ -21,6 +30,20 @@ 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 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 +150,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()
@@ -231,6 +283,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 };
@@ -264,9 +321,31 @@ 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);
+        }
+      }
+
+      // 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) {
+        const handoffToken = await new LiveKitTokenService().MintClientToken(roomName, this.participantIdentity(user), user.Name ?? user.Email);
+        return {
+          Success: true,
+          SessionBridgeID: handoffSessionBridgeID,
+          RoomName: roomName,
+          ServerUrl: handoffToken.ServerUrl,
+          ClientToken: handoffToken.Token,
+          Identity: handoffToken.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
@@ -293,6 +372,7 @@ 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,
       });
@@ -332,7 +412,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)}`);
@@ -358,7 +446,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 +460,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 +505,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 +535,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 +582,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 +614,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 +672,55 @@ export class RealtimeBridgeResolver extends ResolverBase {
     }
   }
 
-  /** Builds a stable, lowercased participant identity from the authenticated user. */
+  /**
+   * 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;
+  }
+
+  /** 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. */

package/src/resolvers/RealtimeClientSessionResolver.ts

@@ -48,6 +48,8 @@ import {
     FindIgnoredRealtimeConfigKeys,
     ParseRealtimeTypeConfiguration,
     ResolveEffectiveRealtimeConfig,
+    ResolveRealtimeCoAgentID,
+    FilterAllowedAgentsByCanRun,
     RealtimeAllowedAgent,
     RealtimeDirectActionsConfig,
     REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION,
@@ -56,7 +58,7 @@ import {
     writeRealtimeRecordingSegment,
     deleteRealtimeRecordingSegments,
 } from '@memberjunction/ai-agents';
-import { AgentExecutionProgressCallback, MJAIAgentEntityExtended, AppContextSnapshot } from '@memberjunction/ai-core-plus';
+import { AgentExecutionProgressCallback, AppContextSnapshot } from '@memberjunction/ai-core-plus';
 import { ChatMessage, RealtimeToolDefinition } from '@memberjunction/ai';
 import { ResolverBase } from '../generic/ResolverBase.js';
 import { PUSH_STATUS_UPDATES_TOPIC } from '../generic/PushStatusResolver.js';
@@ -71,32 +73,6 @@ import { ResolveWidgetGuestRunContext, ResolveScopedAnonymousRunUser } from '../
  */
 const SIGNIFICANT_PROGRESS_STEPS = ['prompt_execution', 'action_execution', 'subagent_execution', 'decision_processing'];
 
-/**
- * The seeded name of the internal orchestration agent that fronts a target agent in realtime
- * sessions (voice + interactive channels). This is the GLOBAL DEFAULT co-agent — the final step of
- * the co-agent resolution chain (see {@link RealtimeClientSessionResolver.resolveCoAgentID}).
- * Deployments can override it per agent (`AIAgent.DefaultCoAgentID`), per agent type (an
- * `AIAgentCoAgent` row with `TargetAgentTypeID` + `IsDefault`), or per call (the `coAgentId`
- * mutation argument) without
- * touching this seed.
- */
-const REALTIME_CO_AGENT_NAME = 'Realtime Co-Agent';
-
-/**
- * DEPRECATED legacy seed name of {@link REALTIME_CO_AGENT_NAME}, from before the agent's rename
- * from "Voice Co-Agent" to "Realtime Co-Agent". Deployments that have not re-synced the agent seed
- * still carry this name, so {@link RealtimeClientSessionResolver.resolveGlobalCoAgentID} falls
- * back to it (with a deprecation log) when no agent named {@link REALTIME_CO_AGENT_NAME} exists.
- */
-const LEGACY_REALTIME_CO_AGENT_NAME = 'Voice Co-Agent';
-
-/**
- * The seeded name of the Realtime agent TYPE. Every co-agent candidate (explicit or metadata
- * default) must be an Active agent of this type — a co-agent drives a streaming full-duplex
- * realtime session, which only `RealtimeAgentType`-driven agents support.
- */
-const REALTIME_AGENT_TYPE_NAME = 'Realtime';
-
 /** Entity name — centralised so the `MJ:`-prefix convention is applied in exactly one place. */
 const SESSION_ENTITY = 'MJ: AI Agent Sessions';
 const CO_AGENT_ENTITY = 'MJ: AI Agent Co Agents';
@@ -414,7 +390,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
      *    session is created.
      * 2. Resolve the co-agent id via the metadata-driven resolution chain (runtime `coAgentId` →
      *    agent's `DefaultCoAgentID` → type-level `AIAgentCoAgent` default row → global Realtime Co-Agent) —
-     *    see {@link RealtimeClientSessionResolver.resolveCoAgentID} for the full contract.
+     *    see {@link ResolveRealtimeCoAgentID} for the full contract.
      * 3. Create the durable `AIAgentSession` (run by the co-agent), storing `targetAgentID` in its
      *    config server-side — this is the authoritative target for all later relays.
      * 4. Mint the {@link import('@memberjunction/ai').ClientRealtimeSessionConfig} via the service.
@@ -463,7 +439,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
     ): Promise<StartRealtimeClientSessionResult> {
         const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
 
-        const coAgentID = await this.resolveCoAgentID(targetAgentId, coAgentId, contextUser, provider);
+        const coAgentID = await ResolveRealtimeCoAgentID(targetAgentId, coAgentId, contextUser, provider);
         // PAIRING CONSTRAINTS: a co-agent with pairing rows is restricted to that target list
         // (with the IsDefault row standing in when no runtime target was supplied); zero rows =
         // universal, today's behavior untouched. Resolves the AUTHORITATIVE target id.
@@ -578,7 +554,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                 TargetAgentID: config.targetAgentID,
                 // Multi-target (Move 4): the session's persisted allowed-agent union — a model-named
                 // colleague in the call is validated against this; absent ⇒ single-target behavior.
-                AllowedAgents: await this.filterAllowedAgentsByCanRun(config.allowedAgents, contextUser),
+                AllowedAgents: await FilterAllowedAgentsByCanRun(config.allowedAgents, contextUser),
                 DirectActions: config.directActions,
                 // Attribution follows the VISITOR even when `runUser` is elevated: the delegated run
                 // row and its context-memory scope must stay the person's, not the system user's.
@@ -1250,39 +1226,6 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         }
     }
 
-    /**
-     * Narrows a session's colleague union (`allowedAgents`) to the agents the CALLER may run.
-     *
-     * {@link assertCanRunTarget} gates the LEAD target at session start, but the union it travels
-     * with was never gated at all — a model-named colleague resolves straight to a delegated run.
-     * That was survivable while the run carried the caller's own identity, because base-agent
-     * re-checks `CanRun` against `contextUser`. Once the run user is elevated for a scoped anonymous
-     * caller (issue #3371) that check sees the SYSTEM user, so this is the only remaining place the
-     * caller's own authority is applied to a colleague. It therefore runs for EVERY caller, elevated
-     * or not — the authorization identity must never depend on the elevation decision.
-     *
-     * `HasPermission` reads AIEngineBase's in-memory caches (no DB round trip) and already fails
-     * closed on error, so an unresolvable agent drops OUT of the union rather than becoming runnable.
-     * A filtered-out colleague is not an error: the delegation layer reports it as "not available in
-     * this session" and lists what remains, which is the same answer the model gets for a typo.
-     *
-     * @param allowedAgents The session's persisted colleague union (absent/empty ⇒ single-target).
-     * @param contextUser The ORIGINAL caller — never the elevated run user.
-     * @returns The subset the caller may run, preserving order.
-     */
-    private async filterAllowedAgentsByCanRun(
-        allowedAgents: RealtimeAllowedAgent[] | undefined,
-        contextUser: UserInfo,
-    ): Promise<RealtimeAllowedAgent[] | undefined> {
-        if (!allowedAgents || allowedAgents.length === 0) {
-            return allowedAgents;
-        }
-        const verdicts = await Promise.all(
-            allowedAgents.map((a) => AIAgentPermissionHelper.HasPermission(a.agentId, contextUser, 'run')),
-        );
-        return allowedAgents.filter((_, i) => verdicts[i]);
-    }
-
     /**
      * Resolves the AUTHORITATIVE target agent id under the co-agent's PAIRING CONSTRAINTS
      * (`MJ: AI Agent Co Agents`, ordered by `Sequence`):
@@ -1525,195 +1468,6 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         }
     }
 
-    /**
-     * Resolves the co-agent (the Realtime-type agent that voices the target agent) for a new
-     * client-direct session via the metadata-driven **CO-AGENT RESOLUTION CHAIN** — first match
-     * wins, evaluated in precedence order:
-     *
-     * 1. **Runtime parameter** — the mutation's explicit `coAgentId`. A per-call override; an
-     *    invalid candidate (unknown, not Active, or not of the Realtime agent type) **throws**
-     *    (fail loud — the caller asked for something specific, mirroring `preferredModelId`).
-     * 2. **Per-agent persona** — the target agent's `AIAgent.DefaultCoAgentID`. An invalid
-     *    reference logs a warning and **falls through** to the next step (stale metadata should
-     *    degrade gracefully, never break calls).
-     * 3. **Per-type default** — an Active `AIAgentCoAgent` row of Type `'CoAgent'` whose
-     *    `TargetAgentTypeID` is the target agent's type and `IsDefault = 1` (lowest `Sequence`
-     *    wins a tie). Same tolerant warn-and-fall-through semantics as step 2.
-     * 4. **Global default** — the seeded {@link REALTIME_CO_AGENT_NAME} agent, looked up by name
-     *    (with a deprecated fallback to {@link LEGACY_REALTIME_CO_AGENT_NAME}). Throws when absent
-     *    entirely (the realtime feature is unconfigured in this deployment).
-     *
-     * Every candidate from steps 1–3 is validated by {@link findValidCoAgent}: it must exist in
-     * {@link AIEngine}'s cached agents, have Status `Active`, and be of the
-     * {@link REALTIME_AGENT_TYPE_NAME} agent type. Step 4 keeps its original name-lookup contract.
-     *
-     * @param targetAgentId The agent the co-agent will voice on behalf of (drives steps 2–3).
-     * @param explicitCoAgentId The runtime `coAgentId` mutation argument, when supplied (step 1).
-     * @returns The resolved co-agent's id (canonical casing from the metadata cache).
-     */
-    private async resolveCoAgentID(
-        targetAgentId: string | undefined,
-        explicitCoAgentId: string | undefined,
-        contextUser: UserInfo,
-        provider: IMetadataProvider,
-    ): Promise<string> {
-        await AIEngine.Instance.Config(false, contextUser, provider);
-
-        // Step 1 — explicit runtime parameter: fail LOUD on any problem.
-        if (explicitCoAgentId) {
-            const { agent, problem } = this.findValidCoAgent(explicitCoAgentId);
-            if (!agent) {
-                throw new Error(`Invalid coAgentId '${explicitCoAgentId}': ${problem}`);
-            }
-            return agent.ID;
-        }
-
-        const targetAgent = targetAgentId
-            ? (AIEngine.Instance.Agents ?? []).find(a => UUIDsEqual(a.ID, targetAgentId))
-            : undefined;
-
-        // Step 2 — the target agent's own DefaultCoAgentID (per-agent persona): warn + fall through.
-        const fromAgent = this.resolveMetadataDefault(
-            targetAgent?.DefaultCoAgentID,
-            `agent '${targetAgent?.Name}' (DefaultCoAgentID)`,
-        );
-        if (fromAgent) {
-            return fromAgent;
-        }
-
-        // Step 3 — the type-level AIAgentCoAgent default row (per-type default): warn + fall through.
-        const agentType = targetAgent?.TypeID
-            ? (AIEngine.Instance.AgentTypes ?? []).find(t => UUIDsEqual(t.ID, targetAgent.TypeID))
-            : undefined;
-        const typeDefaultCoAgentID = agentType
-            ? this.findTypeDefaultCoAgentID(agentType.ID, contextUser, provider)
-            : undefined;
-        const fromType = this.resolveMetadataDefault(
-            await typeDefaultCoAgentID,
-            `agent type '${agentType?.Name}' (AIAgentCoAgent type-default row)`,
-        );
-        if (fromType) {
-            return fromType;
-        }
-
-        // Step 4 — global default: the seeded Realtime Co-Agent, by name (original behavior).
-        return this.resolveGlobalCoAgentID();
-    }
-
-    /**
-     * Chain step 3 lookup: the TYPE-LEVEL default co-agent for an agent type — the Active
-     * `AIAgentCoAgent` row of Type `'CoAgent'` whose `TargetAgentTypeID` matches, with
-     * `IsDefault = 1` preferred and the lowest `Sequence` breaking ties (so a deployment can
-     * stage multiple type-level candidates deterministically). Reads {@link AIEngineBase}'s
-     * cached rows — no RunView. Tolerant: a failed cache read logs and returns `undefined`
-     * (the chain falls through to the global default).
-     */
-    private async findTypeDefaultCoAgentID(
-        agentTypeID: string,
-        contextUser: UserInfo,
-        provider: IMetadataProvider,
-    ): Promise<string | undefined> {
-        try {
-            const engine = await this.configuredAIEngineBase(contextUser, provider);
-            const candidates = (engine.AgentCoAgents ?? [])
-                .filter((r) =>
-                    r.Type === 'CoAgent' &&
-                    r.Status === 'Active' &&
-                    r.TargetAgentTypeID != null &&
-                    UUIDsEqual(r.TargetAgentTypeID, agentTypeID))
-                .sort((a, b) =>
-                    (a.IsDefault === b.IsDefault ? 0 : a.IsDefault ? -1 : 1) ||
-                    (a.Sequence ?? 0) - (b.Sequence ?? 0));
-            return candidates[0]?.CoAgentID;
-        } catch (error) {
-            LogError(
-                `StartRealtimeClientSession: ${CO_AGENT_ENTITY} cache read failed while resolving the type-level ` +
-                    `default co-agent for agent type ${agentTypeID} (${(error as Error).message}) — falling through.`,
-            );
-            return undefined;
-        }
-    }
-
-    /**
-     * Validates one metadata-level co-agent default (chain steps 2/3). Returns the resolved
-     * co-agent id when the reference is valid; logs a warning and returns `null` (caller falls
-     * through to the next chain step) when the reference is set but invalid — metadata drift must
-     * degrade, not break live calls. A `null`/absent reference returns `null` silently.
-     */
-    private resolveMetadataDefault(candidateId: string | null | undefined, source: string): string | null {
-        if (!candidateId) {
-            return null;
-        }
-        const { agent, problem } = this.findValidCoAgent(candidateId);
-        if (agent) {
-            return agent.ID;
-        }
-        LogError(
-            `StartRealtimeClientSession: ignoring co-agent default '${candidateId}' from ${source} — ${problem} ` +
-                'Falling through to the next step of the co-agent resolution chain.',
-        );
-        return null;
-    }
-
-    /**
-     * Validates a co-agent candidate against {@link AIEngine}'s cached metadata. A valid co-agent
-     * must (a) exist, (b) have Status `Active`, and (c) be of the {@link REALTIME_AGENT_TYPE_NAME}
-     * agent type. Returns the cached agent on success, or a human-readable `problem` on failure —
-     * the CALLER decides whether that's fatal (explicit runtime param) or tolerated (metadata default).
-     */
-    private findValidCoAgent(candidateId: string): { agent?: MJAIAgentEntityExtended; problem?: string } {
-        const agent = (AIEngine.Instance.Agents ?? []).find(a => UUIDsEqual(a.ID, candidateId));
-        if (!agent) {
-            return { problem: 'no agent with that ID exists.' };
-        }
-        if (agent.Status !== 'Active') {
-            return { problem: `agent '${agent.Name}' is not Active (Status: ${agent.Status}).` };
-        }
-        const realtimeType = (AIEngine.Instance.AgentTypes ?? []).find(
-            t => t.Name?.trim().toLowerCase() === REALTIME_AGENT_TYPE_NAME.toLowerCase(),
-        );
-        if (!realtimeType) {
-            return { problem: `the '${REALTIME_AGENT_TYPE_NAME}' agent type is not configured in this deployment.` };
-        }
-        if (!agent.TypeID || !UUIDsEqual(agent.TypeID, realtimeType.ID)) {
-            return { problem: `agent '${agent.Name}' is not of the '${REALTIME_AGENT_TYPE_NAME}' agent type.` };
-        }
-        return { agent };
-    }
-
-    /**
-     * Resolves the seeded Realtime Co-Agent's id from {@link AIEngine}'s cached agents — the GLOBAL
-     * DEFAULT (step 4) of the co-agent resolution chain. The engine is already configured by
-     * {@link resolveCoAgentID}. Looks up the current {@link REALTIME_CO_AGENT_NAME} first, then
-     * falls back to the DEPRECATED {@link LEGACY_REALTIME_CO_AGENT_NAME} (pre-rename seed) with a
-     * deprecation log so un-resynced deployments keep working. Throws a clear error when neither
-     * name is present in metadata.
-     */
-    private resolveGlobalCoAgentID(): string {
-        const coAgent = this.findAgentByName(REALTIME_CO_AGENT_NAME);
-        if (coAgent) {
-            return coAgent.ID;
-        }
-        const legacy = this.findAgentByName(LEGACY_REALTIME_CO_AGENT_NAME);
-        if (legacy) {
-            LogStatus(
-                `StartRealtimeClientSession: resolved the global co-agent via its DEPRECATED legacy name ` +
-                    `'${LEGACY_REALTIME_CO_AGENT_NAME}'. Re-sync the agent seed metadata to rename it to ` +
-                    `'${REALTIME_CO_AGENT_NAME}'.`,
-            );
-            return legacy.ID;
-        }
-        throw new Error(
-            `The '${REALTIME_CO_AGENT_NAME}' agent is not configured; cannot start a realtime voice session.`,
-        );
-    }
-
-    /** Case/whitespace-insensitive agent lookup by Name in {@link AIEngine}'s cached agents. */
-    private findAgentByName(name: string): MJAIAgentEntityExtended | undefined {
-        const wanted = name.toLowerCase();
-        return (AIEngine.Instance.Agents ?? []).find(a => a.Name?.trim().toLowerCase() === wanted);
-    }
-
     /**
      * Mints the client session config for a just-created session. On failure, closes the session so
      * no half-open record leaks, then throws the service's error message.

package/src/resolvers/adhocTimeout.ts

@@ -0,0 +1,12 @@
+/** The timeout an ad-hoc query gets when the caller names none. */
+const DEFAULT_TIMEOUT_SECONDS = 30;
+
+/**
+ * The timeout an ad-hoc query runs with: what the caller asked for (or the default), but never
+ * longer than the server's `requestTimeout`, so a caller cannot hold a read-only connection longer
+ * than any other request may. `requestTimeoutMs` of 0 or less means the server sets no limit.
+ */
+export function ClampAdhocTimeoutSeconds(requested: number | undefined, requestTimeoutMs: number): number {
+    const seconds = requested != null && requested > 0 ? requested : DEFAULT_TIMEOUT_SECONDS;
+    return requestTimeoutMs > 0 ? Math.min(seconds, Math.max(1, Math.floor(requestTimeoutMs / 1000))) : seconds;
+}