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

package/dist/resolvers/RealtimeClientSessionResolver.js

@@ -23,9 +23,9 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
  * 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`.
  *
@@ -33,19 +33,33 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
  * - **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 { AuthorizationEvaluator, LogError, LogStatus, RunView } from '@memberjunction/core';
+import { AuthorizationEvaluator, LogError, LogErrorEx, LogStatus, RunView } from '@memberjunction/core';
 import { UUIDsEqual, IsValidUUID } from '@memberjunction/global';
+import { ConversationEngine, } from '@memberjunction/core-entities';
 import { AIEngine } from '@memberjunction/aiengine';
-import { AIAgentPermissionHelper, AIEngineBase } from '@memberjunction/ai-engine-base';
-import { RealtimeClientSessionService, RealtimeChannelServerHost, EvaluateRuntimeOverrideAuthorization, FindIgnoredRealtimeConfigKeys, ParseRealtimeTypeConfiguration, ResolveEffectiveRealtimeConfig, REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION, resolveRecordingStorageAccountID, storeRealtimeRecording, writeRealtimeRecordingSegment, deleteRealtimeRecordingSegments, } from '@memberjunction/ai-agents';
+import { AIAgentPermissionHelper, AIEngineBase, HasRealtimeUsage, ParseRealtimeUsageRecord } from '@memberjunction/ai-engine-base';
+import { RealtimeClientSessionService, RealtimeChannelServerHost, EvaluateRuntimeOverrideAuthorization, FindIgnoredRealtimeConfigKeys, ParseRealtimeTypeConfiguration, ResolveEffectiveRealtimeConfig, ResolveRealtimeCoAgentID, FilterAllowedAgentsByCanRun, INVOKE_TARGET_AGENT_TOOL_NAME, REALTIME_ADVANCED_SESSION_CONTROLS_AUTHORIZATION, resolveRecordingStorageAccountID, storeRealtimeRecording, writeRealtimeRecordingSegment, deleteRealtimeRecordingSegments, } from '@memberjunction/ai-agents';
+import { IsValidRealtimeToolDefinition, NormalizeChannelKey, ParseRealtimeChannelCandidates } from '@memberjunction/ai-core-plus';
 import { ResolverBase } from '../generic/ResolverBase.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
  * in {@link import('./RunAIAgentResolver.js').RunAIAgentResolver}. Initialization/validation/finalization
@@ -53,28 +67,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.
+ * 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 REALTIME_CO_AGENT_NAME = 'Realtime Co-Agent';
-/**
- * DEPRECATED legacy seed name of {@link REALTIME_CO_AGENT_NAME}, from before the agent's rename
- * from "Voice Co-Agent" to "Realtime Co-Agent". Deployments that have not re-synced the agent seed
- * still carry this name, so {@link RealtimeClientSessionResolver.resolveGlobalCoAgentID} falls
- * back to it (with a deprecation log) when no agent named {@link REALTIME_CO_AGENT_NAME} exists.
- */
-const LEGACY_REALTIME_CO_AGENT_NAME = 'Voice Co-Agent';
-/**
- * The seeded name of the Realtime agent TYPE. Every co-agent candidate (explicit or metadata
- * default) must be an Active agent of this type — a co-agent drives a streaming full-duplex
- * realtime session, which only `RealtimeAgentType`-driven agents support.
- */
-const REALTIME_AGENT_TYPE_NAME = 'Realtime';
+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';
 const CO_AGENT_ENTITY = 'MJ: AI Agent Co Agents';
@@ -100,7 +96,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;
@@ -144,6 +141,14 @@ __decorate([
     Field(() => String),
     __metadata("design:type", String)
 ], StartRealtimeClientSessionResult.prototype, "ExpiresAt", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], StartRealtimeClientSessionResult.prototype, "Transport", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], StartRealtimeClientSessionResult.prototype, "RelayUrl", void 0);
 __decorate([
     Field(() => String),
     __metadata("design:type", String)
@@ -172,6 +177,14 @@ __decorate([
     Field(() => String, { nullable: true }),
     __metadata("design:type", String)
 ], StartRealtimeClientSessionResult.prototype, "EffectiveConfigJson", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], StartRealtimeClientSessionResult.prototype, "ClientPolicyJson", void 0);
+__decorate([
+    Field(() => String, { nullable: true }),
+    __metadata("design:type", String)
+], StartRealtimeClientSessionResult.prototype, "AvatarStatusJson", void 0);
 StartRealtimeClientSessionResult = __decorate([
     ObjectType()
 ], StartRealtimeClientSessionResult);
@@ -269,6 +282,7 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         // state on — otherwise that cleanup silently no-ops on a freshly-constructed instance.
         this.clientSessionService = new RealtimeClientSessionService();
         this.sessionManager = new SessionManager(this.clientSessionService);
+        this.runIDVerifier = new SessionRunIDVerifier();
     }
     /**
      * The reason a `Save()`/`Delete()` returned false, for a log line. `CompleteMessage` renders
@@ -302,9 +316,9 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      *    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.
      *
@@ -330,12 +344,18 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      *   `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.
      */
-    async StartRealtimeClientSession(targetAgentId, { userPayload, providers }, conversationId, lastSessionId, preferredModelId, clientToolsJson, coAgentId, configOverridesJson, recordingStartedAt, recordingConsent, mediaCollectionId, applicationId, appContextJson) {
+    async StartRealtimeClientSession(targetAgentId, { userPayload, providers }, conversationId, lastSessionId, preferredModelId, clientToolsJson, coAgentId, configOverridesJson, recordingStartedAt, recordingConsent, mediaCollectionId, applicationId, appContextJson, channelCandidatesJson, showsAgentVideo, conversationBranchId) {
         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.
@@ -367,16 +387,24 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
                     'using the agent default media kit.');
             }
         }
-        const session = await this.sessionManager.CreateSession({
+        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);
+        }, 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.
@@ -385,19 +413,83 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         // mid-thread knows what was already typed. The legs above are excluded: they are already
         // 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);
-        const result = await this.prepareClientSessionOrClose(session, coAgentID, effectiveTargetId, contextUser, provider, preferredModelId, clientTools, prior?.Text, configOverridesJson, maxSessionSeconds, applicationId, this.parseAppContext(appContextJson), conversationMessages);
+        const conversationMessages = await this.loadConversationHistory(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
+     */
+    async resolveSessionBranch(conversationId, branchId, contextUser, provider) {
+        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.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.
+     */
+    async stampVerificationPolicy(session, effectiveConfigJson, lastSessionId, contextUser, provider) {
+        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. */
+    readEffectiveRealtime(effectiveConfigJson) {
+        if (!effectiveConfigJson) {
+            return undefined;
+        }
+        try {
+            return JSON.parse(effectiveConfigJson).realtime;
+        }
+        catch (error) {
+            LogError(`RealtimeClientSessionResolver: effective config JSON was unparseable while stamping verification policy: ${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.
      */
@@ -405,12 +497,17 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         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} ` +
                 'under the system user (scoped-anonymous caller).');
@@ -422,21 +519,28 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             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);
         const durationMs = Date.now() - startTime;
         LogStatus(`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, toolName, argsJson, ResultJson, durationMs, contextUser, provider);
         }
         // Roll the paused-run id forward in the session config: clear the one we just consumed, and
@@ -474,6 +578,18 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             }), userPayload);
         };
     }
+    /**
+     * 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.
+     */
+    refuseDirectAction(agentSessionId, toolName) {
+        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
@@ -485,17 +601,10 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         if (!previous && !pausedRunID) {
             return;
         }
-        const next = {
-            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(`RealtimeClientSessionResolver.updatePendingFeedbackRunID save failed for session ${session.ID}: ${this.describeSaveFailure(session)}`);
@@ -527,9 +636,10 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         // 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), provider);
+            await this.clientSessionService.AppendPromptRunMessage(promptRunID, this.mapTranscriptRoleToChatRole(role), text, replacesPrevious ?? false, runUser, provider);
         }
         await this.sessionManager.Heartbeat(agentSessionId, contextUser, provider);
         return true;
@@ -573,11 +683,11 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         if (consent !== true) {
             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('MJ: AI Agents', runUser);
             if (!(await agent.Load(session.AgentID))) {
@@ -623,11 +733,14 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
     }
     /**
      * 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.
@@ -639,6 +752,12 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         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('MJ: AI Agents', runUser);
@@ -682,11 +801,12 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         // Persist the tool turn facts into a hidden ConversationDetail turn so session review
         // can reconstruct the tool card dynamically on load (Option 1). Best-effort.
         await this.persistDirectActionTurn(session, undefined, toolName, argsJson, resultJson, undefined, contextUser, provider);
-        const promptRunID = this.readPromptRunID(session);
+        const runUser = ResolveScopedAnonymousRunUser(contextUser);
+        const promptRunID = await this.readPromptRunID(session, runUser, provider);
         if (!promptRunID) {
             return false;
         }
-        return this.clientSessionService.AppendPromptRunMessage(promptRunID, 'assistant', this.formatToolTurn(toolName, argsJson, resultJson), false, ResolveScopedAnonymousRunUser(contextUser), provider);
+        return this.clientSessionService.AppendPromptRunMessage(promptRunID, 'assistant', this.formatToolTurn(toolName, argsJson, resultJson), false, runUser, provider);
     }
     /**
      * Formats a co-agent tool call into a compact, human-readable run line: `🔧 <tool> <args> → <result>`,
@@ -749,31 +869,56 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      * (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.
      */
-    async RelayRealtimeUsage(agentSessionId, inputTokens, outputTokens, { userPayload, providers }) {
+    async RelayRealtimeUsage(agentSessionId, inputTokens, outputTokens, { userPayload, providers }, usageDetailsJson) {
         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);
+        return this.clientSessionService.AccumulatePromptRunUsage(promptRunID, inputDelta, outputDelta, runUser, provider, details ?? undefined);
     }
     /** Clamps a relayed token delta: negative / non-finite values become 0. */
     clampTokenDelta(value) {
         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.
+     */
+    readUsageDetails(usageDetailsJson) {
+        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
@@ -792,23 +937,29 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
     }
     /**
      * 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.
      */
-    readPromptRunID(session) {
-        try {
-            const config = this.readSessionConfig(session);
-            if (config.promptRunID) {
-                return config.promptRunID;
-            }
+    async readPromptRunID(session, runUser, provider) {
+        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;
     }
     /**
      * Persist an interactive channel's state of record (e.g. the live whiteboard's serialized
@@ -834,6 +985,10 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
     async SaveSessionChannelState(agentSessionId, channelName, stateJson, { userPayload, providers }) {
         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}' ` +
                 `(${stateJson.length} chars > ${MAX_CHANNEL_STATE_CHARS}).`);
@@ -896,6 +1051,11 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
     async SaveSessionChannelArtifact(agentSessionId, channelName, name, contentJson, { userPayload, providers }) {
         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}' ` +
                 `(${contentJson.length} chars > ${MAX_CHANNEL_STATE_CHARS}).`;
@@ -923,8 +1083,10 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         return { contextUser, provider: GetReadWriteProvider(providers) };
     }
     /**
-     * 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.
      */
     async assertCanRunTarget(targetAgentId, contextUser, _provider) {
         const canRun = await AIAgentPermissionHelper.HasPermission(targetAgentId, contextUser, 'run');
@@ -932,33 +1094,6 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             throw new Error(`Not authorized: you are not permitted to run the target agent ${targetAgentId}`);
         }
     }
-    /**
-     * 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.
-     */
-    async filterAllowedAgentsByCanRun(allowedAgents, contextUser) {
-        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`):
@@ -1162,158 +1297,6 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             return false;
         }
     }
-    /**
-     * 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).
-     */
-    async resolveCoAgentID(targetAgentId, explicitCoAgentId, contextUser, provider) {
-        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).
-     */
-    async findTypeDefaultCoAgentID(agentTypeID, contextUser, provider) {
-        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.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.
-     */
-    resolveMetadataDefault(candidateId, source) {
-        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).
-     */
-    findValidCoAgent(candidateId) {
-        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.
-     */
-    resolveGlobalCoAgentID() {
-        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. */
-    findAgentByName(name) {
-        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.
@@ -1325,8 +1308,9 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      *   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`).
      */
-    async prepareClientSessionOrClose(session, coAgentID, targetAgentId, contextUser, provider, preferredModelId, clientTools, priorTranscript, configOverridesJson, maxSessionSeconds, applicationId, appContext, conversationMessages) {
+    async prepareClientSessionOrClose(session, coAgentID, targetAgentId, contextUser, provider, preferredModelId, clientTools, priorTranscript, configOverridesJson, maxSessionSeconds, applicationId, appContext, conversationMessages, channelCandidates, showsAgentVideo) {
         const prep = await this.clientSessionService.PrepareClientSession({
             CoAgentID: coAgentID,
             TargetAgentID: targetAgentId,
@@ -1352,6 +1336,14 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             // (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
@@ -1364,7 +1356,8 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             await this.sessionManager.CloseSession(session.ID, contextUser, provider, 'Error');
             throw new Error(prep.ErrorMessage ?? 'Failed to prepare the client realtime session.');
         }
-        await this.persistObservabilityRunIDs(session, targetAgentId, prep.CoAgentRunID, prep.PromptRunID, prep.CoAgentRunStepID, applicationId, prep.EffectiveConfig?.realtime?.allowedAgents, prep.EffectiveConfig?.realtime?.directActions);
+        await this.persistObservabilityRunIDs(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 {
             AgentSessionId: session.ID,
@@ -1373,40 +1366,91 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             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.
+     */
+    pruneExcludedServerChannels(agentSessionID, policy) {
+        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.
-     */
-    async persistObservabilityRunIDs(session, targetAgentID, coAgentRunID, promptRunID, coAgentRunStepID, applicationID, allowedAgents, directActions) {
-        // 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);
+     * `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.
+     */
+    async persistObservabilityRunIDs(session, targetAgentID, coAgentRunID, promptRunID, coAgentRunStepID, applicationID, allowedAgents, directActions, channels, appContext) {
+        // 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)}`);
         }
     }
+    /**
+     * 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`.
+     */
+    appContextToStore(appContext, sessionID) {
+        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.
@@ -1601,6 +1645,10 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      * 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.
      *
@@ -1608,19 +1656,28 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      * @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.
      */
-    async loadConversationHistory(conversationId, coveredSessionIDs, contextUser, provider) {
+    async loadConversationHistory(conversationId, coveredSessionIDs, contextUser, provider, branchId) {
         if (!conversationId) {
             return [];
         }
+        const rv = RunView.FromMetadataProvider(provider);
+        let pathFilter;
+        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.message}`);
+            return [];
+        }
         try {
-            const rv = RunView.FromMetadataProvider(provider);
             const result = await rv.RunView({
                 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);
             if (!result.Success) {
@@ -1909,6 +1966,7 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         const detail = await provider.GetEntityObject(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).';
@@ -2037,18 +2095,50 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
     }
     /** Shape check for one client tool declaration: Name/Description non-empty strings, ParametersSchema a plain object. */
     isValidClientTool(candidate) {
-        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.
+     */
+    parseChannelCandidates(channelCandidatesJson) {
+        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.
+     */
+    isChannelInSessionScope(session, channelName) {
+        // 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;
-        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. */
+    sessionBranchIdOf(session) {
+        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.
      */
     readSessionConfig(session) {
         const raw = session.Config_;
@@ -2064,10 +2154,16 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
                         pendingFeedbackRunID: typeof parsed.pendingFeedbackRunID === 'string' ? parsed.pendingFeedbackRunID : undefined,
                         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
                             : 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) => typeof k === 'string') : undefined,
                     };
                 }
             }
@@ -2133,6 +2229,7 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
         const detail = await provider.GetEntityObject(CONVERSATION_DETAIL_ENTITY, contextUser);
         detail.NewRecord();
         detail.ConversationID = session.ConversationID;
+        detail.BranchID = this.sessionBranchIdOf(session);
         detail.Role = this.mapTranscriptRole(role);
         detail.Message = text;
         detail.AgentSessionID = session.ID;
@@ -2270,6 +2367,7 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             const detail = await provider.GetEntityObject(CONVERSATION_DETAIL_ENTITY, contextUser);
             detail.NewRecord();
             detail.ConversationID = session.ConversationID;
+            detail.BranchID = this.sessionBranchIdOf(session);
             detail.Role = 'AI';
             detail.HiddenToUser = true;
             detail.AgentSessionID = session.ID;
@@ -2331,8 +2429,11 @@ __decorate([
     __param(10, Arg('mediaCollectionId', () => String, { nullable: true })),
     __param(11, Arg('applicationId', () => String, { nullable: true })),
     __param(12, Arg('appContextJson', () => String, { nullable: true })),
+    __param(13, Arg('channelCandidatesJson', () => String, { nullable: true })),
+    __param(14, Arg('showsAgentVideo', () => Boolean, { nullable: true })),
+    __param(15, Arg('conversationBranchId', () => String, { nullable: true })),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Object, String, String, String, String, String, String, String, Boolean, String, String, String]),
+    __metadata("design:paramtypes", [String, Object, String, String, String, String, String, String, String, Boolean, String, String, String, String, Boolean, String]),
     __metadata("design:returntype", Promise)
 ], RealtimeClientSessionResolver.prototype, "StartRealtimeClientSession", null);
 __decorate([
@@ -2410,8 +2511,9 @@ __decorate([
     __param(1, Arg('inputTokens', () => Int)),
     __param(2, Arg('outputTokens', () => Int)),
     __param(3, Ctx()),
+    __param(4, Arg('usageDetailsJson', () => String, { nullable: true })),
     __metadata("design:type", Function),
-    __metadata("design:paramtypes", [String, Number, Number, Object]),
+    __metadata("design:paramtypes", [String, Number, Number, Object, String]),
     __metadata("design:returntype", Promise)
 ], RealtimeClientSessionResolver.prototype, "RelayRealtimeUsage", null);
 __decorate([