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

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,25 +33,45 @@ 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, ResolveRealtimeCoAgentID, FilterAllowedAgentsByCanRun, 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';
+import { LoadOwnedRealtimeSession } from '../realtimeSessions/ownedRealtimeSession.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
  * noise is dropped so the model only narrates meaningful work.
  */
 const SIGNIFICANT_PROGRESS_STEPS = ['prompt_execution', 'action_execution', 'subagent_execution', 'decision_processing'];
+/**
+ * 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 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';
@@ -77,7 +97,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;
@@ -121,6 +142,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)
@@ -149,6 +178,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);
@@ -211,7 +248,7 @@ export { CancelRealtimeSessionToolResult };
  * Result of {@link RealtimeClientSessionResolver.UploadRealtimeRecording} — a structured
  * success/failure envelope. A recording-storage failure must never throw to the browser (the
  * session it belongs to has already ended), so problems come back as `Success: false` with a
- * human-readable reason; only ownership/authn violations (from `loadOwnedSession`) still throw.
+ * human-readable reason; only ownership/authn violations (from `LoadOwnedRealtimeSession`) still throw.
  */
 let UploadRealtimeRecordingResult = class UploadRealtimeRecordingResult {
 };
@@ -246,6 +283,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
@@ -281,7 +319,7 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      *    agent's `DefaultCoAgentID` → type-level `AIAgentCoAgent` default row → global Realtime Co-Agent) —
      *    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.
      *
@@ -307,10 +345,16 @@ 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 ResolveRealtimeCoAgentID(targetAgentId, coAgentId, contextUser, provider);
         // PAIRING CONSTRAINTS: a co-agent with pairing rows is restricted to that target list
@@ -344,16 +388,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.
@@ -362,19 +414,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.
      */
@@ -382,12 +498,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).');
@@ -400,20 +521,27 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
             // 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 FilterAllowedAgentsByCanRun(config.allowedAgents, contextUser),
-            DirectActions: config.directActions,
+            // 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
@@ -451,6 +579,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
@@ -462,17 +602,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)}`);
@@ -504,9 +637,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;
@@ -525,7 +659,7 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      * the call and uploads the assembled blob (base64) once the session ends.
      *
      * Hard gates (in order):
-     * 1. Ownership — `loadOwnedSession` enforces `UserID === contextUser.ID` (throws on violation).
+     * 1. Ownership — `LoadOwnedRealtimeSession` enforces `UserID === contextUser.ID` (throws on violation).
      * 2. Consent — `consent !== true` is a hard refusal: no audio is ever stored without it.
      * 3. Storage configuration — the session's agent must resolve a recording storage account (the
      *    agent's `RecordingStorageProviderID`, else `AttachmentStorageProviderID`).
@@ -545,16 +679,16 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      */
     async UploadRealtimeRecording(agentSessionId, audioBase64, mimeType, ctx, durationMs, consent, peaks) {
         const { contextUser, provider } = this.requireUserAndProvider(ctx.userPayload, ctx.providers);
-        const session = await this.loadOwnedSession(agentSessionId, contextUser, provider);
+        const session = await LoadOwnedRealtimeSession(agentSessionId, contextUser, provider);
         // HARD consent gate — no audio is ever stored without an explicit grant.
         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))) {
@@ -600,11 +734,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.
@@ -615,7 +752,13 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
     async UploadRealtimeRecordingSegment(agentSessionId, segmentIndex, audioBase64, mimeType, ctx) {
         try {
             const { contextUser, provider } = this.requireUserAndProvider(ctx.userPayload, ctx.providers);
-            const session = await this.loadOwnedSession(agentSessionId, contextUser, provider);
+            const session = await LoadOwnedRealtimeSession(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);
@@ -659,11 +802,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>`,
@@ -699,7 +843,7 @@ let RealtimeClientSessionResolver = class RealtimeClientSessionResolver extends
      */
     async CancelRealtimeSessionTool(agentSessionId, { userPayload, providers }, callId) {
         const { contextUser, provider } = this.requireUserAndProvider(userPayload, providers);
-        await this.loadOwnedSession(agentSessionId, contextUser, provider);
+        await LoadOwnedRealtimeSession(agentSessionId, contextUser, provider);
         try {
             const aborted = this.clientSessionService.CancelInFlightDelegations(agentSessionId, callId);
             return { AbortedCount: aborted, Success: true };
@@ -726,31 +870,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 session = await LoadOwnedRealtimeSession(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
@@ -769,23 +938,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
@@ -810,7 +985,11 @@ 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);
+        const session = await LoadOwnedRealtimeSession(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}).`);
@@ -872,7 +1051,12 @@ 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);
+        const session = await LoadOwnedRealtimeSession(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}).`;
@@ -900,8 +1084,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');
@@ -1123,8 +1309,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,
@@ -1150,6 +1337,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
@@ -1162,7 +1357,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,
@@ -1171,68 +1367,102 @@ 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.
      */
     async loadOwnedActiveSession(agentSessionId, contextUser, provider) {
-        const session = await this.loadOwnedSession(agentSessionId, contextUser, provider);
+        const session = await LoadOwnedRealtimeSession(agentSessionId, contextUser, provider);
         if (session.Status === 'Closed') {
             throw new Error(`Realtime session ${agentSessionId} is closed`);
         }
         return session;
     }
-    /**
-     * Loads a session and enforces inbound ownership (`UserID === contextUser.ID`) WITHOUT
-     * rejecting `Closed` sessions — {@link SaveSessionChannelState}'s final on-end flush
-     * legitimately arrives after the session closed. Throws when not found / not owned.
-     */
-    async loadOwnedSession(agentSessionId, contextUser, provider) {
-        const session = await provider.GetEntityObject(SESSION_ENTITY, contextUser);
-        const loaded = await session.Load(agentSessionId);
-        if (!loaded) {
-            throw new Error(`Realtime session ${agentSessionId} not found`);
-        }
-        if (!UUIDsEqual(session.UserID, contextUser.ID)) {
-            LogError(`RealtimeClientSessionResolver: ownership check failed — user ${contextUser.ID} attempted to operate on session ${agentSessionId} owned by ${session.UserID}`);
-            throw new Error('Not authorized: you do not own this realtime session');
-        }
-        return session;
-    }
     /**
      * Resolves an ACTIVE channel definition (`MJ: AI Agent Channels`) by name from
      * {@link AIEngineBase}'s cached `AgentChannels` (provider-scoped engine instance, lazy
@@ -1399,6 +1629,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.
      *
@@ -1406,19 +1640,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) {
@@ -1707,6 +1950,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).';
@@ -1835,18 +2079,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_;
@@ -1862,10 +2138,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,
                     };
                 }
             }
@@ -1931,6 +2213,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;
@@ -2068,6 +2351,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;
@@ -2129,8 +2413,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([
@@ -2208,8 +2495,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([