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

package/src/resolvers/GetDataContextDataResolver.ts

@@ -1,9 +1,13 @@
 import { Arg, Ctx, Field, ObjectType, Query, Resolver } from "type-graphql";
+import type { DatabaseProviderBase, UserInfo } from "@memberjunction/core";
+import { IsValidUUID, UUIDsEqual } from "@memberjunction/global";
+import { DataContext, DataContextItem } from "@memberjunction/data-context";
+import { MJDataContextEntity, MJDataContextItemEntity } from "@memberjunction/core-entities";
+import { RenderPipeline } from "@memberjunction/generic-database-provider";
 import { AppContext } from "../types.js";
-import { DataContext } from "@memberjunction/data-context";
-import { GetReadOnlyDataSource, GetReadOnlyProvider } from "../util.js";
-import { MJDataContextItemEntity } from "@memberjunction/core-entities";
+import { GetReadOnlyProvider } from "../util.js";
 import { ResolverBase } from "../generic/ResolverBase.js";
+import { IsScopeLimitedPrincipal } from "../auth/scopeLimitedPrincipal.js";
 
 @ObjectType()
 export class GetDataContextItemDataOutputType {
@@ -39,6 +43,28 @@ export class GetDataContextDataOutputType {
 }
 
 
+/** The outcome of loading one data context item: its data as JSON, or why it has none. */
+interface ItemOutcome {
+    Result: string | null;
+    Error: string | null;
+}
+
+/** Which `sql` items of a data context may run: the read-only provider, and each refused item's reason. */
+interface SQLItemGate {
+    Provider: DatabaseProviderBase | null;
+    Refusals: Map<DataContextItem, string>;
+}
+
+/**
+ * Loads the data of data contexts and their items.
+ *
+ * Items of type `sql` hold raw SQL, which is held to the rules ExecuteAdhocQuery applies to
+ * caller-supplied SQL. It runs only for the data context's owner or an administrator (Owner-type
+ * user), never for a scope-limited session, only on the read-only provider, and only as a single read
+ * statement over entity base views the caller may read in full. A SQL item that may not run is
+ * refused on its own, and the other items still load. Items of the other types load through entity
+ * permissions for the calling user.
+ */
 @Resolver()
 export class GetDataContextDataResolver extends ResolverBase {
     /**
@@ -52,30 +78,25 @@ export class GetDataContextDataResolver extends ResolverBase {
     ) {
         // Check API key scope authorization for data context read
         await this.CheckAPIKeyScopeAuthorization('datacontext:read', DataContextItemID, appCtx.userPayload);
+        if (!IsValidUUID(DataContextItemID)) {
+            return { Success: false, ErrorMessage: 'DataContextItemID must be a UUID', Result: null };
+        }
 
         try {
-            const ds = GetReadOnlyDataSource(appCtx.dataSources, {
-                allowFallbackToReadWrite: true,
-            })
+            const user: UserInfo = appCtx.userPayload.userRecord;
             const md = GetReadOnlyProvider(appCtx.providers, {allowFallbackToReadWrite: true});
-            const dciData = await md.GetEntityObject<MJDataContextItemEntity>("MJ: Data Context Items", appCtx.userPayload.userRecord);
+            const dciData = await md.GetEntityObject<MJDataContextItemEntity>("MJ: Data Context Items", user);
             if (await dciData.Load(DataContextItemID)) {
                 const dci = DataContext.CreateDataContextItem(); // use class factory to get whatever lowest level sub-class is registered
-                await dci.LoadMetadataFromEntityRecord(dciData, md, appCtx.userPayload.userRecord);
+                await dci.LoadMetadataFromEntityRecord(dciData, md, user);
+                const ownerID = dci.Type === 'sql' ? await this.loadDataContextOwnerID(dciData.DataContextID, md, user) : null;
+                const gate = this.authorizeSQLItems([dci], ownerID, appCtx);
                 // now the metadata is loaded so we can call the regular load function
-                if (await dci.LoadData(ds)) {
-                    return {
-                        Success: true,
-                        ErrorMessage: null,
-                        Result: JSON.stringify(dci.Data),
-                    }
-                }
-                else {
-                    return {
-                        Success: false,
-                        ErrorMessage: 'Error loading data context item data',
-                        Result: null,
-                    }
+                const outcome = await this.loadItem(dci, gate, user, false);
+                return {
+                    Success: outcome.Error === null,
+                    ErrorMessage: outcome.Error,
+                    Result: outcome.Result,
                 }
             }
             else {
@@ -89,14 +110,15 @@ export class GetDataContextDataResolver extends ResolverBase {
         catch (e) {
             return {
                 Success: false,
-                ErrorMessage: e,
+                ErrorMessage: e instanceof Error ? e.message : String(e),
                 Result: null,
             }
         }
     }
 
     /**
-     * Returns data for a given data context.
+     * Returns data for a given data context. `Results` and `ErrorMessages` hold one entry per item, in
+     * item order. `Success` is true, and `ErrorMessages` null, only when every item loaded.
      * @param DataContextID
      */
     @Query(() => GetDataContextDataOutputType)
@@ -106,38 +128,114 @@ export class GetDataContextDataResolver extends ResolverBase {
     ) {
         // Check API key scope authorization for data context read
         await this.CheckAPIKeyScopeAuthorization('datacontext:read', DataContextID, appCtx.userPayload);
+        // DataContext.LoadMetadata places this ID in the item filter, so it must be a plain UUID.
+        if (!IsValidUUID(DataContextID)) {
+            return { Success: false, ErrorMessages: ['DataContextID must be a UUID'], Results: null };
+        }
 
         try {
             // our job here is to load the entire data context, so we do that with the Data Context object
+            const user: UserInfo = appCtx.userPayload.userRecord;
+            const md = GetReadOnlyProvider(appCtx.providers, { allowFallbackToReadWrite: true });
             const dc = new DataContext();
-            const ds = GetReadOnlyDataSource(appCtx.dataSources, {
-                allowFallbackToReadWrite: true,
-            })
-            const success = await dc.Load(DataContextID, ds, true, false, 0, appCtx.userPayload.userRecord);
-            if (success) {
-                const retVal =   {
-                    Success: true,
-                    ErrorMessages: null,
-                    Results: dc.Items.map((item) => {
-                        return JSON.stringify(item.Data);
-                    }),
-                }
-                return retVal;
-            }
-            else {
+            if (!(await dc.LoadMetadata(DataContextID, user, md))) {
                 return {
                     Success: false,
                     ErrorMessages: ['Error loading data context'],
-                    Results: null,    
+                    Results: null,
                 }
             }
+            const gate = this.authorizeSQLItems(dc.Items, dc.MJDataContextEntity.UserID, appCtx);
+            const outcomes = await Promise.all(dc.Items.map((item) => this.loadItem(item, gate, user, true)));
+            const allLoaded = outcomes.every((outcome) => outcome.Error === null);
+            return {
+                Success: allLoaded,
+                ErrorMessages: allLoaded ? null : outcomes.map((outcome) => outcome.Error),
+                Results: outcomes.map((outcome) => outcome.Result),
+            }
         }
         catch (e) {
             return {
                 Success: false,
-                ErrorMessages: [e],
+                ErrorMessages: [e instanceof Error ? e.message : String(e)],
                 Results: null,
             }
         }
     }
-}
+
+    /**
+     * Decides which `sql` items among `items` may run. Returns the read-only provider they run on, and
+     * the reason for each SQL item that may not run.
+     */
+    private authorizeSQLItems(items: DataContextItem[], ownerID: string | null, appCtx: AppContext): SQLItemGate {
+        const refusals = new Map<DataContextItem, string>();
+        const sqlItems = items.filter((item) => item.Type === 'sql');
+        if (sqlItems.length === 0) {
+            return { Provider: null, Refusals: refusals };
+        }
+        const user: UserInfo | undefined = appCtx.userPayload?.userRecord;
+        const provider = GetReadOnlyProvider(appCtx.providers, { allowFallbackToReadWrite: false });
+        for (const item of sqlItems) {
+            const refusal = this.sqlItemRefusal(item, ownerID, user, provider);
+            if (refusal !== null) {
+                refusals.set(item, refusal);
+            }
+        }
+        return { Provider: provider, Refusals: refusals };
+    }
+
+    /** Returns why `item` may not run for `user`, or null when it may. */
+    private sqlItemRefusal(item: DataContextItem, ownerID: string | null, user: UserInfo | undefined, provider: DatabaseProviderBase | null): string | null {
+        if (!user || IsScopeLimitedPrincipal(user)) {
+            return 'SQL data context items cannot be run by a scope-limited or unidentified session.';
+        }
+        if (!this.mayRunDataContextSQL(ownerID, user)) {
+            return 'Only the owner of this data context, or an administrator, may run its SQL items.';
+        }
+        if (!provider) {
+            return 'No read-only data source is configured, so SQL data context items cannot run.';
+        }
+        return this.screenItemSQL(item.SQL ?? '', provider, user);
+    }
+
+    /** True when `user` owns the data context or is an administrator (Owner-type user). */
+    private mayRunDataContextSQL(ownerID: string | null, user: UserInfo): boolean {
+        const isOwner = !!ownerID && UUIDsEqual(ownerID, user.ID);
+        return isOwner || user.Type?.trim().toLowerCase() === 'owner';
+    }
+
+    /**
+     * Returns why `sqlText` may not run, or null when it is a single read statement whose every table
+     * reference is an entity base view `user` may read without row-level or field-level narrowing. It is
+     * the check ExecuteAdhocQuery makes on the rendered SQL.
+     */
+    private screenItemSQL(sqlText: string, provider: DatabaseProviderBase, user: UserInfo): string | null {
+        try {
+            const rendered = RenderPipeline.Run(sqlText, { Platform: provider.PlatformKey, ContextUser: user, RequireReadStatement: true });
+            this.assertFullQueryUsesReadableEntityViews(rendered.Trace.AfterTemplates, provider, user, 'data context SQL');
+            return null;
+        }
+        catch (e) {
+            const reason = e instanceof Error ? e.message : String(e);
+            return reason || 'The SQL of this item did not pass the read-only check.';
+        }
+    }
+
+    /** Loads one item's data unless `gate` refused it. Returns the data as JSON, or why there is none. */
+    private async loadItem(item: DataContextItem, gate: SQLItemGate, user: UserInfo, forceRefresh: boolean): Promise<ItemOutcome> {
+        const refusal = gate.Refusals.get(item);
+        if (refusal !== undefined) {
+            return { Result: null, Error: refusal };
+        }
+        if (await item.LoadData(gate.Provider, forceRefresh, false, 0, user)) {
+            return { Result: JSON.stringify(item.Data), Error: null };
+        }
+        return { Result: null, Error: item.DataLoadingError || 'Error loading data context item data' };
+    }
+
+    /** Returns the owner (`UserID`) of a data context, or null when the caller cannot load it. */
+    private async loadDataContextOwnerID(dataContextID: string, provider: DatabaseProviderBase, user: UserInfo): Promise<string | null> {
+        const dataContext = await provider.GetEntityObject<MJDataContextEntity>('MJ: Data Contexts', user);
+        return (await dataContext.Load(dataContextID)) ? dataContext.UserID : null;
+    }
+}

package/src/resolvers/GetDataResolver.ts

@@ -158,14 +158,17 @@ export class GetDataResolver {
                         // Defense-in-depth: even system-token holders get SELECT-only SQL here.
                         // The read-only pool is the primary control, but if it is ever
                         // misconfigured to a read-write login this validator still refuses DML/DDL
-                        // (mirrors AdhocQueryResolver).
-                        const validation = SQLExpressionValidator.Instance.validateFullQuery(resolvedSQL);
+                        // (mirrors AdhocQueryResolver). The validator reads exactly the text that
+                        // runs: it is trimmed here as validate() trims it, and literal \n sequences
+                        // are not rewritten as ValidateFullQuery would.
+                        const sqlToRun = resolvedSQL.trim();
+                        const validation = SQLExpressionValidator.Instance.validate(sqlToRun, { context: 'full_query', Dialect: platform });
                         if (!validation.valid) {
                             return { result: null, error: validation.error || 'SQL validation failed' };
                         }
 
                         const request = new sql.Request(readOnlyDataSource);
-                        const result = await request.query(resolvedSQL);
+                        const result = await request.query(sqlToRun);
                         return { result: result.recordset, error: null };
                     } catch (err) {
                         // Extract clean SQL error message

package/src/resolvers/HumanHandoffResolver.ts

@@ -2,9 +2,11 @@ import { Resolver, Mutation, Query, Subscription, Arg, Ctx, Root, ObjectType, Fi
 import { IMetadataProvider, LogError, UserInfo } from '@memberjunction/core';
 import { MJGlobal, UUIDsEqual } from '@memberjunction/global';
 import { NotificationEngine } from '@memberjunction/notifications';
+import { UserCache } from '@memberjunction/generic-database-provider';
 import {
   LiveKitSipService,
   RoomHandoffEngine,
+  HandoffOfferRegistry,
   type HandoffOfferEvent,
   type HandoffOfferView,
   type IHandoffNotifier,
@@ -207,6 +209,12 @@ export class NotificationHandoffNotifier implements IHandoffNotifier {
   }
 }
 
+// The registry's background sweep and list queries run outside any request, so they need a server identity. Resolve the
+// system user lazily: the user cache may not have loaded when this module does.
+HandoffOfferRegistry.Instance.Configure({
+  ResolveContextUser: () => UserCache.Instance.GetSystemUser(),
+});
+
 /**
  * Binds the handoff engine's collaborators that only the server host can supply (same module-load rationale as the other
  * realtime bindings): the pub/sub publisher, the notification sender, and a room-presence check over the LiveKit credentials

package/src/resolvers/IntegrationDiscoveryResolver.ts

@@ -3,7 +3,7 @@ import { CompositeKey, DatabaseProviderBase, EntityInfo, LocalCacheManager, Meta
 import { GetReadOnlyProvider, GetReadWriteProvider } from "../util.js";
 import { NoLog } from "../logging/NoLog.js";
 import { UUIDsEqual } from "@memberjunction/global";
-import { DrainResponseBody } from "@memberjunction/network-utils";
+import { DrainResponseBody, SafeFetch } from "@memberjunction/network-utils";
 import { CronExpressionHelper } from "@memberjunction/scheduling-engine";
 import {
     MJCompanyIntegrationEntity,
@@ -6467,7 +6467,9 @@ export class IntegrationDiscoveryResolver extends ResolverBase {
 
     private async sendWebhook(url: string, payload: Record<string, unknown>): Promise<void> {
         try {
-            const response = await fetch(url, {
+            // SECURITY: the webhook URL is caller-supplied, so go through the SSRF guard —
+            // SafeFetch validates the URL (and every redirect hop) resolves to a public address.
+            const response = await SafeFetch(url, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
                 body: JSON.stringify(payload)

package/src/resolvers/MCPResolver.ts

@@ -639,11 +639,14 @@ export class MCPResolver extends ResolverBase {
             // Publish syncing progress
             this.publishProgress(pubSub, sessionId, user.ID, ConnectionID, 'syncing', 'Synchronizing tools to database...');
 
-            // Perform the sync
-            const syncResult: MCPSyncToolsResult = await manager.syncTools(ConnectionID, { contextUser: user });
-
-            // Remove event listener
-            manager.removeEventListener('toolsSynced', eventHandler);
+            // Perform the sync; always detach the listener, even if syncTools throws, so failed
+            // syncs don't stack handlers on the shared manager.
+            let syncResult: MCPSyncToolsResult;
+            try {
+                syncResult = await manager.syncTools(ConnectionID, { contextUser: user });
+            } finally {
+                manager.removeEventListener('toolsSynced', eventHandler);
+            }
 
             if (!syncResult.success) {
                 this.publishProgress(pubSub, sessionId, user.ID, ConnectionID, 'error', `Sync failed: ${syncResult.error}`);

package/src/resolvers/QueryResolver.ts

@@ -101,6 +101,12 @@ export class RunQueryCacheStatusInput {
 
   @Field(() => Int, { description: 'The number of rows in cached results' })
   rowCount: number;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
+
+  @Field(() => String, {
+    nullable: true,
+    description: "The query definition hash the cached results were written under, as this server returned it. When it differs from the server's, the result is 'stale' with fresh rows. Empty string for a slot with no hash; omit to skip the definition check."
+  })
+  definitionHash?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name, matching its siblings
 }
 
 @InputType()
@@ -140,6 +146,9 @@ export class RunQueryWithCacheCheckResultOutput {
 
   @Field(() => String, { nullable: true, description: 'Error message if status is error' })
   errorMessage?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name — renaming it breaks every client query
+
+  @Field(() => String, { nullable: true, description: "The server's definition hash for the query; store it with the cached results and send it back in cacheStatus.definitionHash" })
+  definitionHash?: string;  // case-violation-ok-legacy-back-compat: the property name is the GraphQL schema field name, matching its siblings
 }
 
 @ObjectType()
@@ -558,6 +567,7 @@ export class RunQueryResolver extends ResolverBase {
         cacheStatus: item.cacheStatus ? {
           maxUpdatedAt: item.cacheStatus.maxUpdatedAt,
           rowCount: item.cacheStatus.rowCount,
+          definitionHash: item.cacheStatus.definitionHash ?? undefined,
         } : undefined,
       }));
 
@@ -572,6 +582,7 @@ export class RunQueryResolver extends ResolverBase {
         maxUpdatedAt: result.maxUpdatedAt,
         rowCount: result.rowCount,
         errorMessage: result.errorMessage,
+        definitionHash: result.definitionHash,
       }));
 
       return {

package/src/resolvers/RealtimeBridgeResolver.ts

@@ -7,8 +7,13 @@ 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';
@@ -18,7 +23,8 @@ 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';
+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.
@@ -44,6 +50,23 @@ LiveKitAgentRoomCoordinator.Instance.SetTurnToolBinder((session, handler) => {
   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
@@ -233,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)
@@ -241,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. */
@@ -300,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(
@@ -331,18 +395,22 @@ export class RealtimeBridgeResolver extends ResolverBase {
         }
       }
 
+      // 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) {
-        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,
+          ServerUrl: clientToken.ServerUrl,
+          ClientToken: clientToken.Token,
+          Identity: clientToken.Identity,
         };
       }
 
@@ -351,6 +419,10 @@ export class RealtimeBridgeResolver extends ResolverBase {
       // 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);
@@ -361,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,
@@ -377,9 +450,6 @@ export class RealtimeBridgeResolver extends ResolverBase {
         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,
@@ -399,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.
    */
@@ -433,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.
    */
@@ -672,6 +744,46 @@ export class RealtimeBridgeResolver extends ResolverBase {
     }
   }
 
+  /**
+   * 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).
@@ -704,6 +816,46 @@ export class RealtimeBridgeResolver extends ResolverBase {
     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 LiveKitUserIdentity(user.ID);