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

package/src/resolvers/RealtimeClientSessionResolver.ts

@@ -11,9 +11,9 @@
  * and **executes** every tool call the browser relays back. The three mutations here cover the MVP:
  *
  * 1. {@link RealtimeClientSessionResolver.StartRealtimeClientSession} — authorize, create the
- *    session (storing the target agent id server-side, authoritatively), mint the ephemeral config.
- * 2. {@link RealtimeClientSessionResolver.ExecuteRealtimeSessionTool} — execute a relayed tool call,
- *    reading the target agent id from the session (NOT the client) so the browser can't swap targets.
+ *    session (storing the target agent id on it), mint the ephemeral config.
+ * 2. {@link RealtimeClientSessionResolver.ExecuteRealtimeSessionTool} — execute a relayed tool call
+ *    for the target agent stored on the session, re-authorized for the caller on every call.
  * 3. {@link RealtimeClientSessionResolver.RelayRealtimeTranscript} — persist a transcript turn as a
  *    `Conversation Detail`.
  *
@@ -21,12 +21,19 @@
  * - **Start**: the caller must have `CanRun` on the *target* agent (the Realtime Co-Agent is an internal
  *   orchestration agent, so the meaningful gate is the agent doing the real work).
  * - **Execute / Relay**: inbound ownership — the session's `UserID` must equal `contextUser.ID`.
+ * - **Session `Config`**: the owner can edit it through the generic entity API, so nothing in it is
+ *   trusted. Execute re-checks `CanRun` on its target, direct actions never come from it, and its
+ *   run ids are used only when {@link SessionRunIDVerifier} finds them to be records of the session.
+ * - **Scope-limited callers** (anonymous and resource-scoped magic-link sessions, including public
+ *   web-widget guests): no direct actions. Their scope exists only as row-level filters, which an
+ *   action can read around, and a scoped anonymous caller's relay runs as the system user. They
+ *   reach the target agent only through `invoke-target-agent`.
  *
  * @module @memberjunction/server
  */
 import { Resolver, Mutation, Arg, Ctx, Int, Float, ObjectType, Field, PubSub, PubSubEngine } from 'type-graphql';
 import { AppContext, UserPayload } from '../types.js';
-import { AuthorizationEvaluator, UserInfo, IMetadataProvider, LogError, LogStatus, RunView, BaseEntity } from '@memberjunction/core';
+import { AuthorizationEvaluator, UserInfo, IMetadataProvider, LogError, LogErrorEx, LogStatus, RunView, BaseEntity } from '@memberjunction/core';
 import { UUIDsEqual, IsValidUUID } from '@memberjunction/global';
 import {
     MJAIAgentEntity,
@@ -36,9 +43,10 @@ import {
     MJArtifactVersionEntity,
     MJConversationDetailArtifactEntity,
     MJConversationDetailEntity,
+    ConversationEngine,
 } from '@memberjunction/core-entities';
 import { AIEngine } from '@memberjunction/aiengine';
-import { AIAgentPermissionHelper, AIEngineBase } from '@memberjunction/ai-engine-base';
+import { AIAgentPermissionHelper, AIEngineBase, HasRealtimeUsage, ParseRealtimeUsageRecord, type RealtimeUsageRecord } from '@memberjunction/ai-engine-base';
 import {
     RealtimeClientSessionService,
     DelegatedRunArtifact,
@@ -48,6 +56,9 @@ import {
     FindIgnoredRealtimeConfigKeys,
     ParseRealtimeTypeConfiguration,
     ResolveEffectiveRealtimeConfig,
+    ResolveRealtimeCoAgentID,
+    FilterAllowedAgentsByCanRun,
+    INVOKE_TARGET_AGENT_TOOL_NAME,
     RealtimeAllowedAgent,
     RealtimeDirectActionsConfig,
     REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION,
@@ -56,13 +67,26 @@ import {
     writeRealtimeRecordingSegment,
     deleteRealtimeRecordingSegments,
 } from '@memberjunction/ai-agents';
-import { AgentExecutionProgressCallback, MJAIAgentEntityExtended, AppContextSnapshot } from '@memberjunction/ai-core-plus';
+import {
+    AgentExecutionProgressCallback,
+    AppContextSnapshot,
+    IsValidRealtimeToolDefinition,
+    NormalizeChannelKey,
+    ParseRealtimeChannelCandidates,
+    type RealtimeChannelCandidate,
+    type RealtimeSessionClientPolicy
+} 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';
 import { GetReadWriteProvider } from '../util.js';
 import { SessionManager } from '../agentSessions/index.js';
-import { ResolveWidgetGuestRunContext, ResolveScopedAnonymousRunUser } from '../realtimeWidget/widgetGuestElevation.js';
+import { SessionRunIDVerifier } from '../agentSessions/SessionRunIDVerifier.js';
+import { IsScopeLimitedPrincipal } from '../auth/scopeLimitedPrincipal.js';
+import { ResolveWidgetGuestRunContext, ResolveScopedAnonymousRunUser, ResolveRecordingStoreUser } from '../realtimeWidget/widgetGuestElevation.js';
+import { RunWithTrustedSessionConfigWrites } from '@memberjunction/core-entities-server';
+import { BuildMintConfigStamps, LoadInheritedVerifiedIdentity } from '../realtimeSessions/sessionConfigStamps.js';
+import { ParseConfigObject } from '../realtimeSessions/verificationCore.js';
 
 /**
  * Progress steps worth narrating to the realtime model — mirrors the normal agent-run path's filter
@@ -72,30 +96,10 @@ 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.
+ * The longest `usageDetailsJson` a usage relay may carry. Every field of both detail blocks fits in a few hundred
+ * characters, so anything longer is not a relay the browser runtime sends.
  */
-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';
+const MAX_USAGE_DETAILS_JSON_LENGTH = 4096;
 
 /** Entity name — centralised so the `MJ:`-prefix convention is applied in exactly one place. */
 const SESSION_ENTITY = 'MJ: AI Agent Sessions';
@@ -124,7 +128,8 @@ const WHITEBOARD_ARTIFACT_TYPE_NAME = 'Whiteboard';
  */
 const MAX_CLIENT_TOOLS = 64;
 /** Maximum accepted size (chars) of the serialized client tool declarations. Raised in step with
- *  {@link MAX_CLIENT_TOOLS} — multi-channel tool sets with verbose descriptions + JSON schemas run large. */
+ *  {@link MAX_CLIENT_TOOLS} — multi-channel tool sets with verbose descriptions + JSON schemas run large.
+ *  Also the largest serialized app-context snapshot stored on the session config. */
 const MAX_CLIENT_TOOLS_JSON_CHARS = 256_000;
 /** Maximum accepted size (chars) of a persisted channel state blob. */
 const MAX_CHANNEL_STATE_CHARS = 2_000_000;
@@ -142,9 +147,9 @@ const MAX_CONVERSATION_HISTORY_TURNS = 30;
 const MAX_CONVERSATION_HISTORY_CHARS = 8_000;
 
 /**
- * Authoritative shape persisted in `AIAgentSession.Config_` for a client-direct voice session.
- * The target agent id is stored here at start and read back on every relay — the browser never
- * re-supplies it, so it cannot swap targets mid-session.
+ * Shape persisted in `AIAgentSession.Config_` for a client-direct voice session. The server writes
+ * it, but the session owner can also edit it through the generic entity API, so relays re-check
+ * what they read from it (see the authorization model above).
  */
 interface RealtimeSessionConfig {
     /** The top-level target agent the co-agent voices on behalf of. */
@@ -181,6 +186,12 @@ interface RealtimeSessionConfig {
      * for observability / continuity; absent when the session carries no app context.
      */
     applicationID?: string;
+    /**
+     * The app-context snapshot the browser sent at session start. Passed into each delegated
+     * target-agent run so its prompt sees the surface context and tools. Absent when the start carried
+     * none, or when its JSON is longer than {@link MAX_CLIENT_TOOLS_JSON_CHARS}.
+     */
+    appContext?: AppContextSnapshot;
     /**
      * The session's effective allowed delegation targets (union from the config cascade, incl. the app's
      * `RelevantAgents`). Persisted at start so each relayed `invoke-target-agent` call can validate a
@@ -199,6 +210,24 @@ interface RealtimeSessionConfig {
      * agent default kit is used (the common case).
      */
     mediaCollectionID?: string;
+    /**
+     * The fork (`MJ: Conversation Branches.ID`) the session was started on, fixed at start; absent means
+     * Main. Every transcript, direct-action and anchor row the session writes carries it.
+     */
+    conversationBranchID?: string;
+    /**
+     * Server-authoritative identity-verification state (policy snapshot taken at mint, pending/verified
+     * state written by `RealtimeSessionVerificationService`). Protected from owner writes by
+     * `MJAIAgentSessionEntityServer`; opaque to this resolver beyond preserving it across config rewrites.
+     */
+    identityVerification?: Record<string, unknown>;
+    /**
+     * The keys of the interactive channels the session's resolved scope put IN the session (registry
+     * kill switch, agent and app configuration applied). Persisted at start so a later server-side
+     * call naming a channel — a state or artifact save — can check it is actually in scope. Absent
+     * (an unscoped session: a client that reported no channel candidates) ⇒ no channel check.
+     */
+    channels?: string[];
 }
 
 /**
@@ -223,14 +252,32 @@ export class StartRealtimeClientSessionResult {
     @Field(() => String)
     Model: string;
 
-    /** The short-lived client secret the browser presents to the provider to authenticate. */
+    /**
+     * The short-lived client secret the browser presents to the provider to authenticate. Empty on a relay session
+     * ({@link StartRealtimeClientSessionResult.Transport} `relay`), whose {@link StartRealtimeClientSessionResult.RelayUrl}
+     * carries the relay's ticket instead.
+     */
     @Field(() => String)
     EphemeralToken: string;
 
-    /** ISO-8601 timestamp at which {@link StartRealtimeClientSessionResult.EphemeralToken} expires. */
+    /** ISO-8601 timestamp at which {@link StartRealtimeClientSessionResult.EphemeralToken} (or a relay session's ticket) expires. */
     @Field(() => String)
     ExpiresAt: string;
 
+    /**
+     * How the browser reaches the provider: `direct` (with the ephemeral token) or `relay` (through MJAPI's realtime
+     * relay at {@link StartRealtimeClientSessionResult.RelayUrl}). Null means direct.
+     */
+    @Field(() => String, { nullable: true })
+    Transport?: string;
+
+    /**
+     * Where a relay session's browser connects (MJAPI's realtime relay). Null on a direct session. The URL carries the
+     * session's ticket, so it is a credential and is never logged.
+     */
+    @Field(() => String, { nullable: true })
+    RelayUrl?: string;
+
     /** JSON string of the provider-native session config the browser applies verbatim. */
     @Field(() => String)
     SessionConfigJson: string;
@@ -287,6 +334,25 @@ export class StartRealtimeClientSessionResult {
      */
     @Field(() => String, { nullable: true })
     EffectiveConfigJson?: string;
+
+    /**
+     * JSON of the server's resolved channel policy for this session (`RealtimeSessionClientPolicy`):
+     * which of the channel candidates the browser reported are in the session (registry kill switch,
+     * agent and app `channels` configuration applied), with each one's resolved display and config,
+     * plus the app/static client-tool tiers. Null when the caller reported no channel candidates (a
+     * client that predates channel scoping) — the browser then resolves the scope locally.
+     */
+    @Field(() => String, { nullable: true })
+    ClientPolicyJson?: string;
+
+    /**
+     * JSON of the session's live-avatar status (`RealtimeAvatarStatus` from `@memberjunction/ai`): whether the voiced
+     * agent asked for an avatar, whether the model renders it, and why not. The browser reads it after connecting and
+     * tells the user once when the call is audio only. Null when the agent asked for no avatar (its video setting is
+     * off).
+     */
+    @Field(() => String, { nullable: true })
+    AvatarStatusJson?: string;
 }
 
 /**
@@ -380,6 +446,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
     // state on — otherwise that cleanup silently no-ops on a freshly-constructed instance.
     private readonly clientSessionService = new RealtimeClientSessionService();
     private readonly sessionManager = new SessionManager(this.clientSessionService);
+    private readonly runIDVerifier = new SessionRunIDVerifier();
 
     /**
      * The reason a `Save()`/`Delete()` returned false, for a log line. `CompleteMessage` renders
@@ -414,9 +481,9 @@ 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.
+     *    config — the target later relays use, re-authorized for the caller on each relay.
      * 4. Mint the {@link import('@memberjunction/ai').ClientRealtimeSessionConfig} via the service.
      *    On failure the just-created session is closed so no half-open session leaks.
      *
@@ -442,6 +509,12 @@ export class RealtimeClientSessionResolver extends ResolverBase {
      *   `TypeConfiguration` ← this). **Authorization-gated**: requires the
      *   `Realtime: Advanced Session Controls` authorization — unauthorized callers receive a
      *   structured rejection (never a silent ignore). Must be a JSON object.
+     * @param showsAgentVideo `false` from an app that shows no agent video (no channel of it shows it: the embeddable
+     *   widgets, the mobile app): the session asks the model for no avatar, and `AvatarStatusJson` says `host`. Absent or
+     *   `true`: the app may show it. It only ever turns video off, so it needs no authorization.
+     * @param conversationBranchId Optional fork (`MJ: Conversation Branches.ID`) the session starts on;
+     *   omitted is Main. It must be a fork of `conversationId`, else the start fails and no session is
+     *   created. The session's history is read from that fork's path and its transcript is written there.
      *
      * @returns The ephemeral config + session linkage the browser needs to open its socket.
      */
@@ -460,10 +533,13 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         @Arg('mediaCollectionId', () => String, { nullable: true }) mediaCollectionId?: string,
         @Arg('applicationId', () => String, { nullable: true }) applicationId?: string,
         @Arg('appContextJson', () => String, { nullable: true }) appContextJson?: string,
+        @Arg('channelCandidatesJson', () => String, { nullable: true }) channelCandidatesJson?: string,
+        @Arg('showsAgentVideo', () => Boolean, { nullable: true }) showsAgentVideo?: boolean,
+        @Arg('conversationBranchId', () => String, { nullable: true }) conversationBranchId?: string,
     ): 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.
@@ -497,22 +573,32 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                 );
             }
         }
-        const session = await this.sessionManager.CreateSession(
-            {
-                agentID: coAgentID,
-                userID: contextUser.ID,
-                conversationID: conversationId,
-                lastSessionID: lastSessionId,
-                config: JSON.stringify(config),
-            },
-            contextUser,
-            provider,
+        const sessionBranchId = await this.resolveSessionBranch(conversationId, conversationBranchId, contextUser, provider);
+        if (sessionBranchId) {
+            config.conversationBranchID = sessionBranchId;
+        }
+        // The initial Config carries `maxSessionDeadlineIso` for capped sessions — a server-authoritative key
+        // that `MJAIAgentSessionEntityServer` refuses to let the session OWNER write, so this write (and only
+        // this one, built entirely from server-decided values) runs in the trusted scope.
+        const session = await RunWithTrustedSessionConfigWrites(() =>
+            this.sessionManager.CreateSession(
+                {
+                    agentID: coAgentID,
+                    userID: contextUser.ID,
+                    conversationID: conversationId,
+                    lastSessionID: lastSessionId,
+                    config: JSON.stringify(config),
+                },
+                contextUser,
+                provider,
+            ),
         );
 
         // Best-effort: stamp recording-start metadata when the browser captured (with consent) at start.
         await this.stampRecordingStart(session, recordingConsent, recordingStartedAt);
 
         const clientTools = this.parseClientTools(clientToolsJson);
+        const channelCandidates = this.parseChannelCandidates(channelCandidatesJson);
         // Best-effort model-context hydration: the PRIOR session chain's transcript (ownership-
         // checked, capped) is framed into the system prompt so the model REMEMBERS the last leg.
         // Strictly tolerant — any problem yields no hydration, never a failed start.
@@ -522,24 +608,103 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         // framed as the resumed transcript, and injecting the same turns twice puts two accounts of
         // the same exchange in one prompt.
         const conversationMessages = await this.loadConversationHistory(
-            conversationId, prior?.LegIDs ?? [], contextUser, provider,
+            conversationId, prior?.LegIDs ?? [], contextUser, provider, sessionBranchId,
         );
         const result = await this.prepareClientSessionOrClose(
             session, coAgentID, effectiveTargetId, contextUser, provider, preferredModelId, clientTools, prior?.Text,
             configOverridesJson, maxSessionSeconds, applicationId, this.parseAppContext(appContextJson), conversationMessages,
+            channelCandidates, showsAgentVideo,
         );
+        await this.stampVerificationPolicy(session, result.EffectiveConfigJson, lastSessionId, contextUser, provider);
         // Best-effort restore of the PRIOR session's persisted channel states (e.g. the whiteboard
         // board). Strictly tolerant — any problem yields a null field, never a failed start.
         result.PriorChannelStatesJson = (await this.loadPriorChannelStatesJson(lastSessionId, contextUser, provider)) ?? undefined;
         return result;
     }
 
+    /**
+     * The fork a session starts on: null (Main) when none is named; else the named fork, which must
+     * belong to the session's conversation. Returns the fork's stored id.
+     * @throws when a fork is named without a conversation, or is not a fork of it, or the fork rows cannot be read
+     */
+    private async resolveSessionBranch(
+        conversationId: string | undefined,
+        branchId: string | undefined,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<string | null> {
+        const named = branchId?.trim();
+        if (!named) {
+            return null;
+        }
+        if (!conversationId) {
+            throw new Error(`StartRealtimeClientSession: fork ${named} needs a conversation`);
+        }
+        try {
+            const scope = await ConversationEngine.LoadScope(conversationId, named, contextUser, provider);
+            return scope.BranchID;
+        } catch (error) {
+            throw new Error(`StartRealtimeClientSession: fork ${named} is not a readable fork of conversation ${conversationId}: ${(error as Error).message}`);
+        }
+    }
+
+    /**
+     * Stamps the identity-verification policy snapshot, the configured unverified duration cap and any
+     * verified identity inherited from the resumed session onto the new session's `Config`.
+     *
+     * The effective config (config cascade) is only known after prepare, so this is a second, narrowly
+     * scoped write: it runs only when there is something to stamp. It **fails closed** — a cap that could
+     * not be applied would leave the session uncapped, so on a save failure the session is closed and the
+     * start fails rather than proceeding without its limits.
+     */
+    private async stampVerificationPolicy(
+        session: MJAIAgentSessionEntity,
+        effectiveConfigJson: string | undefined,
+        lastSessionId: string | undefined,
+        contextUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<void> {
+        const plan = BuildMintConfigStamps({
+            EffectiveRealtime: this.readEffectiveRealtime(effectiveConfigJson),
+            ExistingConfigRaw: session.Config_,
+            InheritedVerified: await LoadInheritedVerifiedIdentity(lastSessionId, contextUser, provider),
+            NowMs: Date.now(),
+        });
+        if (!plan) {
+            return;
+        }
+        session.Config_ = plan.NextConfigRaw;
+        const saved = await RunWithTrustedSessionConfigWrites(() => session.Save());
+        if (!saved) {
+            LogError(
+                `RealtimeClientSessionResolver.stampVerificationPolicy save failed for session ${session.ID}: ${this.describeSaveFailure(session)}`,
+            );
+            await this.sessionManager.CloseSession(session.ID, contextUser, provider, 'Error');
+            throw new Error('Failed to apply the session limits; the realtime session was not started.');
+        }
+    }
+
+    /** The `realtime` section of the resolved effective config JSON, or undefined when absent/unparseable. */
+    private readEffectiveRealtime(effectiveConfigJson: string | undefined): unknown {
+        if (!effectiveConfigJson) {
+            return undefined;
+        }
+        try {
+            return (JSON.parse(effectiveConfigJson) as { realtime?: unknown }).realtime;
+        } catch (error) {
+            LogError(`RealtimeClientSessionResolver: effective config JSON was unparseable while stamping verification policy: ${(error as Error).message}`);
+            return undefined;
+        }
+    }
+
     /**
      * Execute a single tool call the browser relayed from its provider socket and return the
      * serialized result for the browser to relay back to the model.
      *
-     * Ownership-gated; the target agent id is read from the **session config** (authoritative), never
-     * from the client. Heartbeats the session on success.
+     * Ownership-gated. The target agent id is read from the session config and `CanRun` on it is
+     * checked for the caller on every call, because the owner can edit the config. A direct-action
+     * call from a scope-limited caller is refused before any elevation. Heartbeats the session on
+     * success.
      *
      * @returns The serialized tool result JSON.
      */
@@ -555,13 +720,23 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
         const session = await this.loadOwnedActiveSession(agentSessionId, contextUser, provider);
         const config = this.readSessionConfig(session);
+        await this.assertCanRunTarget(config.targetAgentID, contextUser, provider);
+        if (toolName !== INVOKE_TARGET_AGENT_TOOL_NAME && IsScopeLimitedPrincipal(contextUser)) {
+            return this.refuseDirectAction(agentSessionId, toolName);
+        }
 
         // SCOPED-ANONYMOUS ELEVATION (issue #3371): once ownership is proven above, the delegated
         // run + its AI-run-entity writes execute as the system user for a scoped anonymous caller
         // (the caller's role deliberately holds no grants on the run entities). The lead
-        // targetAgentID comes from the session config and was CanRun-gated at start; the colleague
-        // union is gated just below, against the CALLER, so elevation never widens agent authority.
+        // targetAgentID is CanRun-gated against the CALLER just above, and the colleague union
+        // just below, so elevation never widens agent authority.
         const runUser = ResolveScopedAnonymousRunUser(contextUser);
+        const runIDs = await this.runIDVerifier.Verify(
+            session.ID,
+            { CoAgentRunID: config.coAgentRunID, PendingFeedbackRunID: config.pendingFeedbackRunID },
+            runUser,
+            provider,
+        );
         if (runUser !== contextUser) {
             LogStatus(
                 `ExecuteRealtimeSessionTool: dispatching relayed tool '${toolName}' for session ${agentSessionId} ` +
@@ -578,17 +753,24 @@ 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),
-                DirectActions: config.directActions,
+                AllowedAgents: await FilterAllowedAgentsByCanRun(config.allowedAgents, contextUser),
+                // No DirectActions: the service takes them from the session's start-time projection
+                // or the target agent's metadata, never from the owner-editable config.
                 // 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.
                 AttributionUserID: contextUser.ID,
                 // Nest the delegated target-agent run under the co-agent observability run (when present).
-                ParentRunID: config.coAgentRunID,
+                ParentRunID: runIDs.CoAgentRunID,
+                // The client-tool channel is keyed on the browser session id, so the delegated run can call
+                // the surface's tools; the session-start app context gives its prompt the surface context.
+                BrowserSessionID: userPayload.sessionId,
+                // The app context is a snapshot the browser sent, so a run elevated to the system user
+                // does not get it in its prompt.
+                AppContext: runUser === contextUser ? config.appContext : undefined,
                 Call: { CallID: callId, ToolName: toolName, Arguments: argsJson },
                 OnProgress: this.buildDelegationProgressCallback(pubSub, userPayload, agentSessionId, callId),
                 // Resume a previously-paused delegated run (if any) with the user's answer.
-                ResumeRunID: config.pendingFeedbackRunID,
+                ResumeRunID: runIDs.PendingFeedbackRunID,
             },
             runUser,
             provider,
@@ -598,7 +780,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             `ExecuteRealtimeSessionTool: completed relayed tool '${toolName}' (callId: ${callId}) in ${durationMs}ms`,
         );
 
-        if (toolName !== 'invoke-target-agent') {
+        if (toolName !== INVOKE_TARGET_AGENT_TOOL_NAME) {
             await this.persistDirectActionTurn(
                 session,
                 callId,
@@ -655,6 +837,19 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         };
     }
 
+    /**
+     * The tool result for a direct-action call from a scope-limited caller (see the authorization
+     * model above). It has the broker's result shape, so the model hears that the tool is not
+     * available and can ask the target agent through `invoke-target-agent` instead.
+     */
+    private refuseDirectAction(agentSessionId: string, toolName: string): string {
+        LogStatus(`ExecuteRealtimeSessionTool: refused direct action '${toolName}' for a scope-limited caller on session ${agentSessionId}.`);
+        return JSON.stringify({
+            success: false,
+            output: `The tool '${toolName}' is not available in this session. Ask the agent to do it with ${INVOKE_TARGET_AGENT_TOOL_NAME}.`,
+        });
+    }
+
     /**
      * Rolls the session's `pendingFeedbackRunID` forward after a relayed tool call. The id we just
      * consumed (resumed or none) is dropped; a new paused run id is stored only when the run paused
@@ -670,17 +865,10 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         if (!previous && !pausedRunID) {
             return;
         }
-        const next: RealtimeSessionConfig = {
-            targetAgentID: config.targetAgentID,
-            coAgentRunID: config.coAgentRunID,
-            promptRunID: config.promptRunID,
-            coAgentRunStepID: config.coAgentRunStepID,
-            pendingFeedbackRunID: pausedRunID,
-            // Preserve the server-authoritative voice deadline across config rewrites.
-            maxSessionDeadlineIso: config.maxSessionDeadlineIso,
-            applicationID: config.applicationID,
-            allowedAgents: config.allowedAgents,
-        };
+        // Start from the RAW stored config so every key survives the rewrite — including the
+        // server-authoritative `maxSessionDeadlineIso` and `identityVerification` (dropping either would be
+        // refused by `MJAIAgentSessionEntityServer`, and silently losing a verification would be worse).
+        const next = { ...ParseConfigObject(session.Config_), targetAgentID: config.targetAgentID, pendingFeedbackRunID: pausedRunID };
         session.Config_ = JSON.stringify(next);
         if (!(await session.Save())) {
             LogError(
@@ -725,14 +913,15 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         // conversation (run-viewer observability parity). Best-effort — never fails the transcript relay.
         // The prompt-run write runs as the scoped-anonymous elevated user (issue #3371) — the visible
         // Conversation Detail above deliberately stays on the caller.
-        const promptRunID = this.readPromptRunID(session);
+        const runUser = ResolveScopedAnonymousRunUser(contextUser);
+        const promptRunID = await this.readPromptRunID(session, runUser, provider);
         if (promptRunID) {
             await this.clientSessionService.AppendPromptRunMessage(
                 promptRunID,
                 this.mapTranscriptRoleToChatRole(role),
                 text,
                 replacesPrevious ?? false,
-                ResolveScopedAnonymousRunUser(contextUser),
+                runUser,
                 provider,
             );
         }
@@ -791,11 +980,11 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             return { Success: false, ErrorMessage: 'Recording consent was not granted.' };
         }
 
-        // SCOPED-ANONYMOUS ELEVATION (issue #3371): past the ownership + consent gates, the store is
-        // server-side plumbing over entities (MJ: AI Agents read, MJ: Files, the file-session link)
-        // the caller's narrow relay role deliberately does not hold. Attribution flows through the
-        // session link, so nothing here depends on the caller's identity.
-        const runUser = ResolveScopedAnonymousRunUser(contextUser);
+        // ELEVATION (issue #3371, #5195): past the ownership + consent gates, the store is server-side
+        // plumbing over entities (MJ: AI Agents read, MJ: Files, the file-session link, the session's
+        // recording stamp) that neither a scoped-anonymous relay role nor the stock UI role holds.
+        // Attribution flows through the session link, so nothing here depends on the caller's identity.
+        const runUser = ResolveRecordingStoreUser(contextUser);
         try {
             const agent = await provider.GetEntityObject<MJAIAgentEntity>('MJ: AI Agents', runUser);
             if (!(await agent.Load(session.AgentID))) {
@@ -846,11 +1035,14 @@ export class RealtimeClientSessionResolver extends ResolverBase {
 
     /**
      * Uploads ONE crash-recovery audio shard (~15s) for an IN-PROGRESS recording into the session's
-     * folder (`realtime-recordings/<sessionId>/seg-NNNN.<ext>`) as a raw storage object. Durability
-     * insurance during a live call so a browser/tab death loses at most the last window; the shards are
-     * deleted once the canonical consolidated file lands via {@link UploadRealtimeRecording}. Ownership-
-     * gated; consent was already established at session start. Best-effort — returns `false` (never
-     * throws) on any problem so a failed shard never disrupts the live call.
+     * folder (`realtime-recordings/<sessionId>/seg-NNNN.r<rate>.pcm` for PCM with a rate in its MIME type,
+     * else the legacy `seg-NNNN.<ext>`) as a raw storage object. Durability insurance during a live call
+     * so a browser/tab death loses at most the last window; the shards are deleted once the canonical
+     * consolidated file lands via {@link UploadRealtimeRecording}, or by the session janitor once it has
+     * recovered a recording from them when that upload never arrives. Ownership-
+     * gated; consent was already established at session start. Refused (`false`) once the session has
+     * its consolidated recording, since nothing would delete a shard written after that. Best-effort —
+     * returns `false` (never throws) on any problem so a failed shard never disrupts the live call.
      *
      * @param agentSessionId The in-progress session (ownership-gated).
      * @param segmentIndex 0-based shard index within the session.
@@ -869,6 +1061,12 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         try {
             const { contextUser, provider } = this.requireUserAndProvider(ctx.userPayload, ctx.providers);
             const session = await this.loadOwnedSession(agentSessionId, contextUser, provider);
+            // The consolidated recording already landed and its upload deleted the shards; a shard
+            // arriving now (one still on the wire at hang-up) would be an orphan nothing deletes.
+            if (session.RecordingFileID) {
+                LogStatus(`RealtimeClientSessionResolver.UploadRealtimeRecordingSegment: shard ${segmentIndex} for session ${agentSessionId} refused — the session already has its consolidated recording`);
+                return false;
+            }
             // Scoped-anonymous elevation (issue #3371) — same rationale as UploadRealtimeRecording.
             const runUser = ResolveScopedAnonymousRunUser(contextUser);
             const agent = await provider.GetEntityObject<MJAIAgentEntity>('MJ: AI Agents', runUser);
@@ -930,7 +1128,8 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             provider,
         );
 
-        const promptRunID = this.readPromptRunID(session);
+        const runUser = ResolveScopedAnonymousRunUser(contextUser);
+        const promptRunID = await this.readPromptRunID(session, runUser, provider);
         if (!promptRunID) {
             return false;
         }
@@ -939,7 +1138,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             'assistant',
             this.formatToolTurn(toolName, argsJson, resultJson),
             false,
-            ResolveScopedAnonymousRunUser(contextUser),
+            runUser,
             provider,
         );
     }
@@ -1011,8 +1210,15 @@ export class RealtimeClientSessionResolver extends ResolverBase {
      * (observability creation was skipped), a failed load, or a failed save all log and return
      * `false` — usage relay must never break a live call.
      *
+     * The optional details are the per-modality usage since the last relay: input and output
+     * blocks shaped like Core's `RealtimeUsageModalityDetail`, avatar video seconds included. They
+     * add into the usage record on the run's `ModelSpecificResponseDetails`, which prices the avatar
+     * video at finalize. Only the fields a block defines, with values that are finite numbers of at
+     * least 0, are kept; a relay that carries only details (avatar seconds, no tokens) is stored.
+     *
      * @param inputTokens Input-token DELTA to add (negative/non-finite values are clamped to 0).
      * @param outputTokens Output-token DELTA to add (negative/non-finite values are clamped to 0).
+     * @param usageDetailsJson The per-modality usage since the last relay, as JSON (`{ Input, Output }`).
      * @returns `true` when the accumulated usage was persisted; `false` on any tolerated failure.
      */
     @Mutation(() => Boolean)
@@ -1021,25 +1227,28 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         @Arg('inputTokens', () => Int) inputTokens: number,
         @Arg('outputTokens', () => Int) outputTokens: number,
         @Ctx() { userPayload, providers }: AppContext,
+        @Arg('usageDetailsJson', () => String, { nullable: true }) usageDetailsJson?: string,
     ): Promise<boolean> {
         const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
         const session = await this.loadOwnedSession(agentSessionId, contextUser, provider);
 
         const inputDelta = this.clampTokenDelta(inputTokens);
         const outputDelta = this.clampTokenDelta(outputTokens);
-        if (inputDelta === 0 && outputDelta === 0) {
+        const details = this.readUsageDetails(usageDetailsJson);
+        if (inputDelta === 0 && outputDelta === 0 && !details) {
             return true; // nothing to add — a no-op flush is a success, not a failure
         }
 
-        const promptRunID = this.readPromptRunID(session);
+        // Runs as the scoped-anonymous elevated user (issue #3371) — the caller's role holds no prompt-run grants.
+        const runUser = ResolveScopedAnonymousRunUser(contextUser);
+        const promptRunID = await this.readPromptRunID(session, runUser, provider);
         if (!promptRunID) {
             return false; // no observability prompt run for this session — logged in the helper
         }
         // Delegate to the service so usage writes share the per-run serialization with transcript-message
         // appends — otherwise the frequent usage save clobbers freshly-appended Messages (and vice-versa).
-        // Runs as the scoped-anonymous elevated user (issue #3371) — the caller's role holds no prompt-run grants.
         return this.clientSessionService.AccumulatePromptRunUsage(
-            promptRunID, inputDelta, outputDelta, ResolveScopedAnonymousRunUser(contextUser), provider,
+            promptRunID, inputDelta, outputDelta, runUser, provider, details ?? undefined,
         );
     }
 
@@ -1048,6 +1257,23 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         return Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
     }
 
+    /**
+     * Reads the relayed per-modality usage, or `null` when there is none worth storing: absent,
+     * malformed, longer than a relay ever needs (a client cannot make the server parse an
+     * arbitrarily large string), or holding no amount above 0.
+     */
+    private readUsageDetails(usageDetailsJson: string | undefined): RealtimeUsageRecord | null {
+        if (typeof usageDetailsJson !== 'string') {
+            return null;
+        }
+        if (usageDetailsJson.length > MAX_USAGE_DETAILS_JSON_LENGTH) {
+            LogError(`RelayRealtimeUsage: usage details of ${usageDetailsJson.length} characters exceed ${MAX_USAGE_DETAILS_JSON_LENGTH} — details dropped.`);
+            return null;
+        }
+        const details = ParseRealtimeUsageRecord(usageDetailsJson);
+        return HasRealtimeUsage(details) ? details : null;
+    }
+
     /**
      * Sanitizes client-supplied waveform peaks before they're persisted: drops anything that isn't a
      * finite number, clamps each to `[0, 1]`, and caps the array length so a hostile client can't bloat
@@ -1067,24 +1293,40 @@ export class RealtimeClientSessionResolver extends ResolverBase {
 
     /**
      * Reads the co-agent `AIPromptRun` id from the session config WITHOUT the relay path's
-     * throw-on-missing-target semantics — usage relay is best-effort, so a missing/malformed
-     * config or absent id just logs and returns `null`.
+     * throw-on-missing-target semantics, and keeps it only when it is the prompt run of the
+     * session's co-agent run (the owner can edit the config). Usage relay is best-effort, so a
+     * missing/malformed config, an absent id, or an id of another session just logs and returns `null`.
+     *
+     * @param runUser The user the prompt-run write runs as; the check runs as the same user.
      */
-    private readPromptRunID(session: MJAIAgentSessionEntity): string | null {
-        try {
-            const config = this.readSessionConfig(session);
-            if (config.promptRunID) {
-                return config.promptRunID;
-            }
+    private async readPromptRunID(
+        session: MJAIAgentSessionEntity,
+        runUser: UserInfo,
+        provider: IMetadataProvider,
+    ): Promise<string | null> {
+        const config = this.tryReadSessionConfig(session);
+        if (!config) {
+            LogError(`RelayRealtimeUsage: session ${session.ID} has no parseable config — usage delta dropped.`);
+            return null;
+        }
+        if (!config.promptRunID) {
             LogStatus(
                 `RelayRealtimeUsage: session ${session.ID} has no co-agent promptRunID (observability run ` +
                     'creation was skipped or failed) — usage delta dropped.',
             );
             return null;
-        } catch {
-            LogError(`RelayRealtimeUsage: session ${session.ID} has no parseable config — usage delta dropped.`);
+        }
+        const verified = await this.runIDVerifier.Verify(
+            session.ID,
+            { CoAgentRunID: config.coAgentRunID, PromptRunID: config.promptRunID },
+            runUser,
+            provider,
+        );
+        if (!verified.PromptRunID) {
+            LogError(`RelayRealtimeUsage: session ${session.ID} names a promptRunID that is not its co-agent prompt run — ignored.`);
             return null;
         }
+        return verified.PromptRunID;
     }
 
     /**
@@ -1118,6 +1360,10 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
         const session = await this.loadOwnedSession(agentSessionId, contextUser, provider);
 
+        if (!this.isChannelInSessionScope(session, channelName)) {
+            LogError(`SaveSessionChannelState: channel '${channelName}' is not in session ${agentSessionId}'s resolved scope — state not saved.`);
+            return false;
+        }
         if (stateJson.length > MAX_CHANNEL_STATE_CHARS) {
             LogError(
                 `SaveSessionChannelState: rejected oversized state for session ${agentSessionId} / channel '${channelName}' ` +
@@ -1197,6 +1443,11 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
         const session = await this.loadOwnedSession(agentSessionId, contextUser, provider);
 
+        if (!this.isChannelInSessionScope(session, channelName)) {
+            const message = `SaveSessionChannelArtifact: channel '${channelName}' is not in session ${agentSessionId}'s resolved scope — nothing saved.`;
+            LogError(message);
+            return { Success: false, ErrorMessage: message, ConversationDetailLinked: false };
+        }
         if (contentJson.length > MAX_CHANNEL_STATE_CHARS) {
             const message =
                 `SaveSessionChannelArtifact: rejected oversized content for session ${agentSessionId} / channel '${channelName}' ` +
@@ -1234,8 +1485,10 @@ export class RealtimeClientSessionResolver extends ResolverBase {
     }
 
     /**
-     * Authorization gate for {@link RealtimeClientSessionResolver.StartRealtimeClientSession}: the
-     * caller must be able to run the **target** agent. Denial throws (no session is created).
+     * Authorization gate for the **target** agent: the caller must be able to run it. Denial throws.
+     * {@link RealtimeClientSessionResolver.StartRealtimeClientSession} runs it before any session is
+     * created, and {@link RealtimeClientSessionResolver.ExecuteRealtimeSessionTool} runs it on every
+     * relayed call, because the owner can edit the target in the session config.
      */
     private async assertCanRunTarget(
         targetAgentId: string,
@@ -1250,39 +1503,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 +1745,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.
@@ -1725,6 +1756,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
      *   resumed session remembers the previous leg(s).
      * @param conversationMessages Optional capped history of the TEXT conversation this session is
      *   starting from (from {@link loadConversationHistory}) — framed as "Conversation so far".
+     * @param showsAgentVideo `false` when the app shows no agent video: the session asks for no avatar (`host`).
      */
     private async prepareClientSessionOrClose(
         session: MJAIAgentSessionEntity,
@@ -1740,6 +1772,8 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         applicationId?: string,
         appContext?: AppContextSnapshot,
         conversationMessages?: ChatMessage[],
+        channelCandidates?: RealtimeChannelCandidate[],
+        showsAgentVideo?: boolean,
     ): Promise<StartRealtimeClientSessionResult> {
         const prep = await this.clientSessionService.PrepareClientSession(
             {
@@ -1767,6 +1801,14 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                 // (allowed-agent union); the snapshot is injected into the system prompt at mint.
                 ApplicationID: applicationId,
                 AppContext: appContext,
+                // Scope-limited callers get no direct actions (see the authorization model above), so
+                // the model is not given tools that the relay refuses.
+                ExcludeDirectActions: IsScopeLimitedPrincipal(contextUser),
+                // The channels the browser could mount: scoped here (registry + cascade) and handed back
+                // as the resolved policy; the declared tools are narrowed to match.
+                ChannelCandidates: channelCandidates,
+                // An app with no channel that shows the agent's video: no avatar is asked for (reason `host`).
+                ShowsAgentVideo: showsAgentVideo ?? undefined,
             },
             // SCOPED-ANONYMOUS ELEVATION (issue #3371): the prepare creates the co-agent
             // observability AIAgentRun/AIPromptRun/run-step, which a scoped anonymous caller's role
@@ -1787,7 +1829,10 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             session, targetAgentId, prep.CoAgentRunID, prep.PromptRunID, prep.CoAgentRunStepID,
             applicationId, prep.EffectiveConfig?.realtime?.allowedAgents,
             prep.EffectiveConfig?.realtime?.directActions,
+            prep.ClientPolicy?.Channels.map((c) => c.Key),
+            appContext,
         );
+        this.pruneExcludedServerChannels(session.ID, prep.ClientPolicy);
 
         const cfg = prep.ClientConfig;
         return {
@@ -1797,20 +1842,43 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             Model: cfg.Model,
             EphemeralToken: cfg.EphemeralToken,
             ExpiresAt: cfg.ExpiresAt,
+            Transport: cfg.Transport,
+            RelayUrl: cfg.RelayUrl,
             SessionConfigJson: JSON.stringify(cfg.SessionConfig),
             ModelName: prep.ModelName,
             DriverClass: prep.DriverClass,
             NarrationInstructionsTemplate: prep.NarrationInstructionsTemplate,
             NarrationPaceMs: prep.NarrationPaceMs,
             EffectiveConfigJson: prep.EffectiveConfig ? JSON.stringify(prep.EffectiveConfig) : undefined,
+            ClientPolicyJson: prep.ClientPolicy ? JSON.stringify(prep.ClientPolicy) : undefined,
+            AvatarStatusJson: prep.AvatarStatus ? JSON.stringify(prep.AvatarStatus) : undefined,
         };
     }
 
+    /**
+     * Drops the server-side channel plugins of channels the resolved scope left out. Server plugins
+     * start when the session row is created — before the scope is known — so an excluded channel's
+     * server half would otherwise keep running. A no-op when the caller reported no candidates.
+     */
+    private pruneExcludedServerChannels(agentSessionID: string, policy: RealtimeSessionClientPolicy | undefined): void {
+        const excluded = (policy?.ExcludedChannels ?? []).map((e) => e.Key);
+        if (excluded.length === 0) {
+            return;
+        }
+        const dropped = RealtimeChannelServerHost.Instance.PruneSessionChannels(agentSessionID, excluded);
+        if (dropped.length > 0) {
+            LogStatus(`StartRealtimeClientSession: dropped the server plugins of out-of-scope channel(s) [${dropped.join(', ')}] for session ${agentSessionID}.`);
+        }
+    }
+
     /**
      * Writes the co-agent observability run ids into the session's `Config_` alongside the
-     * authoritative `targetAgentID`, then saves the session. These ids are read back on close to
-     * finalize the runs (and on relay to nest delegated runs). Best-effort: a save failure is logged,
-     * not thrown — the voice session still proceeds, it just won't carry the run ids.
+     * `targetAgentID`, then saves the session. These ids are read back on close to
+     * finalize the runs (and on relay to nest delegated runs). The app awareness (application id,
+     * allowed agents, direct actions, app-context snapshot) is written with them; relays read the
+     * allowed agents and the app context, never the direct actions.
+     * Best-effort: a save failure is logged, not thrown — the voice session still proceeds, it just
+     * won't carry the run ids.
      */
     private async persistObservabilityRunIDs(
         session: MJAIAgentSessionEntity,
@@ -1821,22 +1889,29 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         applicationID?: string,
         allowedAgents?: RealtimeAllowedAgent[],
         directActions?: RealtimeDirectActionsConfig,
+        channels?: string[],
+        appContext?: AppContextSnapshot,
     ): Promise<void> {
-        // Preserve any server-authoritative voice deadline stamped at session start (this rebuilds the
-        // full config, so read the existing value forward rather than dropping it).
-        const existing = this.tryReadSessionConfig(session);
-        const config: RealtimeSessionConfig = {
+        // Start from the RAW stored config so every key set at session start survives — the
+        // server-authoritative voice deadline (`maxSessionDeadlineIso`) and the per-session media-kit
+        // override among them — rather than rebuilding from a whitelist that silently drops the rest.
+        const config = {
+            ...ParseConfigObject(session.Config_),
             targetAgentID,
             coAgentRunID,
             promptRunID,
             coAgentRunStepID,
-            maxSessionDeadlineIso: existing?.maxSessionDeadlineIso,
             applicationID,
+            appContext: this.appContextToStore(appContext, session.ID),
             allowedAgents: allowedAgents && allowedAgents.length > 0 ? allowedAgents : undefined,
             directActions,
+            channels,
         };
         session.Config_ = JSON.stringify(config);
-        const saved = await session.Save();
+        // Every value written here is server-decided (run ids, the resolved target, the in-scope channel
+        // set), and `channels` is a server-authoritative key the owner may not write — so this save runs in
+        // the trusted scope. Protected keys already in the stored config are carried forward unchanged.
+        const saved = await RunWithTrustedSessionConfigWrites(() => session.Save());
         if (!saved) {
             LogError(
                 `RealtimeClientSessionResolver.persistObservabilityRunIDs save failed for session ${session.ID}: ${this.describeSaveFailure(session)}`,
@@ -1844,6 +1919,32 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         }
     }
 
+    /**
+     * Returns the app-context snapshot to store on the session config. A snapshot whose JSON is longer
+     * than {@link MAX_CLIENT_TOOLS_JSON_CHARS} is not stored: a warning is logged and `undefined` is
+     * returned, so the session still starts and its delegated runs get no app context.
+     *
+     * @param appContext The snapshot the browser sent at session start, or undefined.
+     * @param sessionID The session the snapshot belongs to (for the warning).
+     * @returns The snapshot to store, or `undefined`.
+     */
+    private appContextToStore(appContext: AppContextSnapshot | undefined, sessionID: string): AppContextSnapshot | undefined {
+        if (!appContext) {
+            return undefined;
+        }
+        const chars = JSON.stringify(appContext).length;
+        if (chars > MAX_CLIENT_TOOLS_JSON_CHARS) {
+            LogErrorEx({
+                message:
+                    `RealtimeClientSessionResolver: app context for session ${sessionID} not stored — ${chars} chars ` +
+                    `exceeds the ${MAX_CLIENT_TOOLS_JSON_CHARS} cap; delegated runs get no app context.`,
+                severity: 'warning',
+            });
+            return undefined;
+        }
+        return appContext;
+    }
+
     /**
      * Loads a session, enforcing inbound ownership (`UserID === contextUser.ID`) and that it is not
      * `Closed`. Throws on any violation. Returns the loaded session for the caller to read from.
@@ -2089,6 +2190,10 @@ export class RealtimeClientSessionResolver extends ResolverBase {
      * as the resumed transcript are removed, so the prompt never carries two accounts of one
      * exchange.
      *
+     * Only the rows on the session's path that no rerun replaced are read: the fork it started on,
+     * or Main, in `Sequence` order. When that path cannot be built — its branch rows are missing or invalid — the session
+     * starts with no history, never with every branch's rows.
+     *
      * Strictly tolerant — no conversation, a failed read, or any throw yields `[]`, never a failed
      * session start. The call still works; it just starts cold.
      *
@@ -2096,6 +2201,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
      * @param coveredSessionIDs Session ids already framed via `PriorTranscript`.
      * @param contextUser The calling user (RunView scope — the read is row-level-secured).
      * @param provider The request-scoped metadata provider.
+     * @param branchId The fork the session started on; null is Main.
      * @returns The capped history, oldest first.
      */
     private async loadConversationHistory(
@@ -2103,12 +2209,22 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         coveredSessionIDs: string[],
         contextUser: UserInfo,
         provider: IMetadataProvider,
+        branchId: string | null,
     ): Promise<ChatMessage[]> {
         if (!conversationId) {
             return [];
         }
+        const rv = RunView.FromMetadataProvider(provider);
+        let pathFilter: string;
+        try {
+            pathFilter = await ConversationEngine.BranchPathFilterFresh(conversationId, branchId, contextUser, provider);
+        } catch (error) {
+            LogError(
+                `StartRealtimeClientSession: could not build the path of the session's view for conversation ${conversationId}: ${(error as Error).message}`,
+            );
+            return [];
+        }
         try {
-            const rv = RunView.FromMetadataProvider(provider);
             const result = await rv.RunView<{
                 Role: string;
                 Message: string | null;
@@ -2117,9 +2233,9 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             }>(
                 {
                     EntityName: CONVERSATION_DETAIL_ENTITY,
-                    ExtraFilter: `ConversationID='${conversationId.replace(/'/g, "''")}'`,
+                    ExtraFilter: ConversationEngine.LiveRowsFilter(pathFilter),
                     Fields: ['ID', 'Role', 'Message', 'HiddenToUser', 'AgentSessionID', '__mj_CreatedAt'],
-                    OrderBy: '__mj_CreatedAt ASC',
+                    OrderBy: 'Sequence ASC',
                     ResultType: 'simple',
                 },
                 contextUser,
@@ -2486,6 +2602,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         const detail = await provider.GetEntityObject<MJConversationDetailEntity>(CONVERSATION_DETAIL_ENTITY, callerUser);
         detail.NewRecord();
         detail.ConversationID = session.ConversationID;
+        detail.BranchID = this.sessionBranchIdOf(session);
         detail.Role = 'AI';
         detail.HiddenToUser = true;
         detail.Message = 'Artifacts produced during a realtime session (system anchor).';
@@ -2638,21 +2755,54 @@ export class RealtimeClientSessionResolver extends ResolverBase {
 
     /** Shape check for one client tool declaration: Name/Description non-empty strings, ParametersSchema a plain object. */
     private isValidClientTool(candidate: unknown): boolean {
-        if (candidate === null || typeof candidate !== 'object' || Array.isArray(candidate)) {
+        return IsValidRealtimeToolDefinition(candidate);
+    }
+
+    /**
+     * Tolerantly parses the channel candidates the browser reported at mint (the same caps and
+     * tolerance as {@link parseClientTools}: capped, never throws, anything wrong is dropped and
+     * logged). A caller that sent none yields `undefined` — an unscoped session, exactly as before.
+     */
+    private parseChannelCandidates(channelCandidatesJson?: string): RealtimeChannelCandidate[] | undefined {
+        const parsed = ParseRealtimeChannelCandidates(channelCandidatesJson);
+        for (const reason of parsed.Rejected) {
+            LogError(`StartRealtimeClientSession: ${reason}.`);
+        }
+        return parsed.Candidates.length > 0 ? parsed.Candidates : undefined;
+    }
+
+    /**
+     * Whether a session's persisted scope allows a server-side call to name `channelName`. A session
+     * with no persisted scope (it reported no candidates) is unscoped and allows everything; a scoped
+     * one allows only the channels its policy put in the session.
+     */
+    private isChannelInSessionScope(session: MJAIAgentSessionEntity, channelName: string): boolean {
+        // Read the RAW config: an absent `channels` key means an unscoped session, but anything present
+        // and malformed fails CLOSED — a scope that cannot be read must not widen to "everything".
+        // (`channels` is a server-authoritative key, so the owner cannot delete it to unscope a session.)
+        const channels = ParseConfigObject(session.Config_)['channels'];
+        if (channels === undefined) {
+            return true;
+        }
+        if (!Array.isArray(channels)) {
+            LogError(`RealtimeClientSessionResolver: session ${session.ID} has a malformed channel scope; refusing channel '${channelName}'.`);
             return false;
         }
-        const tool = candidate as Partial<RealtimeToolDefinition>;
-        return (
-            typeof tool.Name === 'string' && tool.Name.trim().length > 0 && tool.Name.length <= 128 &&
-            typeof tool.Description === 'string' && tool.Description.trim().length > 0 &&
-            tool.ParametersSchema !== null && typeof tool.ParametersSchema === 'object' && !Array.isArray(tool.ParametersSchema)
-        );
+        const wanted = NormalizeChannelKey(channelName);
+        return channels.some((key) => typeof key === 'string' && NormalizeChannelKey(key) === wanted);
+    }
+
+    /** The fork the session was started on (its config's `conversationBranchID`); null is Main. */
+    private sessionBranchIdOf(session: MJAIAgentSessionEntity): string | null {
+        const branchId = ParseConfigObject(session.Config_)['conversationBranchID'];
+        return typeof branchId === 'string' && branchId.length > 0 ? branchId : null;
     }
 
     /**
-     * Parses the session's persisted config, returning the authoritative `targetAgentID` plus any
-     * observability run ids (`coAgentRunID`/`promptRunID`). Throws when the config is missing/malformed
-     * or carries no target — a relay cannot proceed without a target.
+     * Parses the session's persisted config, returning its `targetAgentID` plus any observability run
+     * ids (`coAgentRunID`/`promptRunID`). Throws when the config is missing/malformed or carries no
+     * target — a relay cannot proceed without a target. The owner can edit the config, so callers
+     * re-check what they act on.
      */
     private readSessionConfig(session: MJAIAgentSessionEntity): RealtimeSessionConfig {
         const raw = session.Config_;
@@ -2670,11 +2820,18 @@ export class RealtimeClientSessionResolver extends ResolverBase {
                         maxSessionDeadlineIso:
                             typeof parsed.maxSessionDeadlineIso === 'string' ? parsed.maxSessionDeadlineIso : undefined,
                         applicationID: typeof parsed.applicationID === 'string' ? parsed.applicationID : undefined,
+                        appContext:
+                            parsed.appContext && typeof parsed.appContext === 'object' && !Array.isArray(parsed.appContext)
+                                ? parsed.appContext
+                                : undefined,
                         allowedAgents: Array.isArray(parsed.allowedAgents) ? parsed.allowedAgents : undefined,
                         directActions:
                             parsed.directActions && typeof parsed.directActions === 'object' && typeof parsed.directActions.enabled === 'boolean'
                                 ? (parsed.directActions as RealtimeDirectActionsConfig)
                                 : undefined,
+                        conversationBranchID: typeof parsed.conversationBranchID === 'string' ? parsed.conversationBranchID : undefined,
+                        mediaCollectionID: typeof parsed.mediaCollectionID === 'string' ? parsed.mediaCollectionID : undefined,
+                        channels: Array.isArray(parsed.channels) ? parsed.channels.filter((k): k is string => typeof k === 'string') : undefined,
                     };
                 }
             } catch {
@@ -2762,6 +2919,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
         );
         detail.NewRecord();
         detail.ConversationID = session.ConversationID;
+        detail.BranchID = this.sessionBranchIdOf(session);
         detail.Role = this.mapTranscriptRole(role);
         detail.Message = text;
         detail.AgentSessionID = session.ID;
@@ -2935,6 +3093,7 @@ export class RealtimeClientSessionResolver extends ResolverBase {
             );
             detail.NewRecord();
             detail.ConversationID = session.ConversationID;
+            detail.BranchID = this.sessionBranchIdOf(session);
             detail.Role = 'AI';
             detail.HiddenToUser = true;
             detail.AgentSessionID = session.ID;