@memberjunction/ai-agents 6.2.0-edge.2 → 6.2.0-edge.4

package/dist/realtime/realtime-client-session-service.js

@@ -29,19 +29,89 @@
  * @module @memberjunction/ai-agents
  * @author MemberJunction.com
  */
-import { LogError, LogStatus, RunView } from '@memberjunction/core';
-import { MJGlobal, MJLruCache, UUIDsEqual, EscapeSQLString } from '@memberjunction/global';
+import { LogError, LogStatus, RunView, DatabaseProviderBase } from '@memberjunction/core';
+import { MJGlobal, MJLruCache, UUIDsEqual, EscapeSQLString, NormalizeUUID } from '@memberjunction/global';
 import { ActionEngineServer } from '@memberjunction/actions';
 import { RunActionParams } from '@memberjunction/actions-base';
-import { BaseRealtimeModel, GetAIAPIKey } from '@memberjunction/ai';
-import { FormatAppContextNote, ResolvePromptRunUserID } from '@memberjunction/ai-core-plus';
+import { BaseRealtimeModel, GetAIAPIKey, CredentialScopeAllows, IsZeroDataRetention } from '@memberjunction/ai';
+import { FormatAppContextNote, ResolvePromptRunUserID, ClientToolMetadataFromDefinition, ParseAgentSettings, ResolveAppClientToolMetadata, ResolveClientTools } from '@memberjunction/ai-core-plus';
 import { AIEngine } from '@memberjunction/aiengine';
+import { RealtimeSessionCanShowAvatar, ResolveBridgedAvatarStatus, ResolveRealtimeAvatar, ResolveRealtimeAvatarStatus, WithoutUnseenAvatar, } from './realtime-avatar-resolution.js';
+import { ChooseRealtimeVendorForAvatar, ReadRealtimeVideoOutputRow, RealtimeModelShowsAvatar } from './realtime-video-output-gate.js';
 import { AgentMemoryContextBuilder } from '../agent-memory-context-builder.js';
 import { AgentRunner } from '../AgentRunner.js';
+import { AgentRunWatchdog } from '../agent-run-watchdog.js';
+import { DelegationNarrator } from './realtime-delegation-narrator.js';
+import { FilterAllowedAgentsByCanRun } from './realtime-coagent-resolution.js';
+import { BridgeRealtimeUsageRecorder } from './bridge-realtime-usage-recorder.js';
 import { RealtimeToolBroker, INVOKE_TARGET_AGENT_TOOL_NAME, INVOKE_TARGET_AGENT_DESCRIPTION, BuildRealtimeAgentFraming } from './realtime-tool-broker.js';
 import { NARRATION_PROMPT_NAME, LEGACY_NARRATION_PROMPT_NAME, ResolveNarrationInstructionsTemplate } from './realtime-narration.js';
-import { BuildVoiceMannerSection, BuildAppRealtimeOverridesJson, DeepMergeConfigs, GetModelCatalogSessionSettings, GetDisclosureForTarget, GetNarrationPaceMs, GetProviderVoiceSettings, GetSessionTuningSettings, ResolveEffectiveRealtimeConfig, MatchProviderVoiceSettings, GetDirectActionsConfig, IsActionAllowedForDirectInvocation } from './realtime-coagent-config.js';
-import { SelectRealtimeVendorForModel } from './realtime-vendor-resolution.js';
+import { BuildVoiceMannerSection, BuildAppRealtimeOverridesJson, DeepMergeConfigs, FindDeprecatedRealtimeVideoKeys, GetModelCatalogSessionSettings, GetDisclosureForTarget, GetNarrationPaceMs, GetProviderVoiceSettings, GetSessionTuningSettings, GetWatchesMeetingVideo, ResolveEffectiveRealtimeConfig, MatchProviderVoiceSettings, GetDirectActionsConfig, IsActionAllowedForDirectInvocation } from './realtime-coagent-config.js';
+import { ListRealtimeVendorsForModel, SelectRealtimeVendorForModel } from './realtime-vendor-resolution.js';
+import { AIEngineBase, MergeRealtimeUsageRecord } from '@memberjunction/ai-engine-base';
+import { BuildSessionChannelPolicy } from './realtime-channel-policy.js';
+/**
+ * How many seconds of avatar video a run may store beyond its elapsed time: usage is client-reported, so the stored
+ * output video seconds are capped at the run's elapsed time plus this grace (relays land a few seconds late).
+ */
+const VIDEO_SECONDS_GRACE = 30;
+/**
+ * How long closing a bridged (server-held) session waits for its model session to close before the session's runs are
+ * finalized anyway, in milliseconds. A model session reports its last usage while it closes (a Gemini avatar session,
+ * the seconds of video it has not reported yet), and the runs are priced from what was stored when they are finalized.
+ */
+export const BRIDGE_SESSION_CLOSE_WAIT_MS = 5_000;
+/**
+ * The co-agent and target pairs already named in the deprecated `realtime.video` keys line, so the line is logged once
+ * per pair per process rather than on every session.
+ */
+const deprecatedVideoKeysLogged = new Set();
+/**
+ * How many output video tokens one second of avatar video counts: Gemini counts 258 tokens a frame at 24 frames a
+ * second, the rate the per-minute avatar price is derived from. The stored output video tokens are capped at the
+ * seconds cap at this rate, because pricing uses them: they leave the cost row's output bucket, and a per-token avatar
+ * price prices them. Raise it for a model that counts more.
+ */
+const VIDEO_TOKENS_PER_SECOND = 6192;
+/** Runtime handles by their realtime session, so the layer that only holds the session can reach its runtime. */
+const bridgeRuntimes = new WeakMap();
+/**
+ * Returns the runtime wired onto a bridged realtime session by
+ * {@link RealtimeClientSessionService.WireBridgeRealtimeSession}, or `undefined` for a session that was never
+ * wired. Lets a host that only holds the {@link IRealtimeSession} (the telephony services) cancel delegations on
+ * barge-in and install its local tool handler.
+ */
+export function GetBridgeRealtimeRuntime(session) {
+    return bridgeRuntimes.get(session);
+}
+/**
+ * Closes a bridged model session, waiting for it up to `waitMs`. Resolves when the close finishes or the wait runs out;
+ * rejects when the close fails within the wait. A close still running when the wait runs out is logged (what the
+ * session reports from then on is not stored), and so is its failure, should it fail later.
+ *
+ * @param close The session's own `Close()`.
+ * @param waitMs How long to wait for it.
+ * @param label Names the session in the log lines (its co-agent prompt run).
+ */
+async function closeBridgedSessionWithin(close, waitMs, label) {
+    const closing = Promise.resolve(close());
+    let timer;
+    const waitRanOut = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(true), waitMs);
+        timer.unref?.();
+    });
+    try {
+        const ranOut = await Promise.race([closing.then(() => false), waitRanOut]);
+        if (ranOut) {
+            LogError(`[Bridged usage] ${label}: the model session took more than ${waitMs} ms to close; its runs are finalized ` +
+                `without waiting, so usage it reports while closing is not stored.`);
+            closing.catch((error) => LogError(`[Bridged usage] ${label}: closing the model session failed: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /**
  * Logs when a configuration authored per-provider voice settings but NONE matched the vendor that
  * actually ran — those settings are dropped, and pre-#3530 that happened with no trace at all: the
@@ -249,7 +319,7 @@ export class RealtimeClientSessionService {
         if (!prep.Success || !prep.CoAgent || !prep.Resolution || !prep.SessionParams || !prep.EffectiveConfig) {
             return { Success: false, ErrorMessage: prep.ErrorMessage };
         }
-        const { CoAgent: coAgent, Resolution: resolution, SessionParams: sessionParams, EffectiveConfig: effectiveConfig } = prep;
+        const { CoAgent: coAgent, Resolution: resolution, SessionParams: sessionParams, EffectiveConfig: effectiveConfig, ClientPolicy: clientPolicy } = prep;
         if (!resolution.Model.SupportsClientDirect) {
             return {
                 Success: false,
@@ -264,6 +334,7 @@ export class RealtimeClientSessionService {
             const message = error instanceof Error ? error.message : String(error);
             return { Success: false, ErrorMessage: `Failed to mint client realtime session: ${message}` };
         }
+        const avatarStatus = this.resolveMintedAvatarStatus(prep, clientConfig);
         // Best-effort observability: create a server-side co-agent run (+ prompt run) so the voice
         // session is visible in the agent-run timeline and delegated runs can nest under it. A
         // failure here never fails the prepare — we just omit the ids.
@@ -281,9 +352,30 @@ export class RealtimeClientSessionService {
             DriverClass: resolution.DriverClass,
             NarrationInstructionsTemplate: this.resolveNarrationInstructionsTemplate() ?? undefined,
             EffectiveConfig: effectiveConfig,
+            ClientPolicy: clientPolicy,
             NarrationPaceMs: GetNarrationPaceMs(effectiveConfig) ?? undefined,
+            ...(avatarStatus ? { AvatarStatus: avatarStatus } : {}),
         };
     }
+    /**
+     * The call's avatar status once the driver has minted the session (see {@link ResolveRealtimeAvatarStatus}), with one
+     * log line saying whether the avatar shows. `undefined`, and no line, when the session asked for no avatar.
+     */
+    resolveMintedAvatarStatus(prep, clientConfig) {
+        const resolution = prep.Resolution;
+        const apiName = resolution?.APIName ?? clientConfig.Model;
+        const status = ResolveRealtimeAvatarStatus({
+            Resolution: prep.AvatarResolution ?? {},
+            ModelSupportsAvatarOutput: resolution
+                ? RealtimeModelShowsAvatar({ ModelID: resolution.ModelID, APIName: apiName, Model: resolution.Model }, AIEngine.Instance)
+                : false,
+            DriverStatus: clientConfig.AvatarStatus,
+        });
+        if (status) {
+            console.log(`[RealtimeCoAgent] mint avatar model=${apiName} shown=${status.Granted} reason=${status.Reason ?? 'none'}`);
+        }
+        return status;
+    }
     /**
      * Wires a **server long-lived (bridged)** realtime session onto the SAME core machinery the
      * client-direct path uses — so a LiveKit (or future Zoom/Teams) agent does real work and is tracked
@@ -294,12 +386,22 @@ export class RealtimeClientSessionService {
      * under the co-agent run, supports barge-in cancel + paused-run resume — all of it, for free).
      *
      * Responsibilities, in order:
+     * 0. Report the avatar status the driver had nothing to say about: a prep that asked the driver for no avatar (a
+     *    phone call, no face for the model's vendor, an unknown avatar, a Video/Output row that turns video off) leaves
+     *    the driver nothing to report, and a driver that renders no avatar ignores a request, so the session's
+     *    `AvatarStatus` says why instead of saying nothing ({@link ResolveBridgedAvatarStatus}).
      * 1. Create the co-agent observability run (+ prompt run + step) so the voice session shows up in the
      *    agent-run timeline and delegated runs nest under it (best-effort; a failure just omits the ids).
-     * 2. Wire `session.OnToolCall` → `ExecuteRelayedTool` → `session.SendToolResult`.
-     * 3. Guarantee finalize-once: wrap `session.Close()` and listen for an unexpected drop (`OnClose`), both
+     * 2. Record the session's usage on the co-agent prompt run, as client-direct calls do: `session.OnUsage` →
+     *    {@link BridgeRealtimeUsageRecorder} → {@link AccumulatePromptRunUsage}, every 10 s and once more at finalize.
+     * 3. Wire `session.OnToolCall` → `ExecuteRelayedTool` → `session.SendToolResult`.
+     * 4. Guarantee finalize-once: wrap `session.Close()` and listen for an unexpected drop (`OnClose`), both
      *    routed through one idempotent finalizer. The bridge teardown calls `Close()`, so the run finalizes
-     *    on graceful end; a dropped socket finalizes via `OnClose`.
+     *    on graceful end; a dropped socket finalizes via `OnClose`, and a `Close()` after it waits for that
+     *    finalize. The wrapped `Close()` closes the model session first (waiting up to
+     *    {@link BRIDGE_SESSION_CLOSE_WAIT_MS}), so the usage it reports while closing is recorded; the
+     *    finalizer then writes the session's last usage before it finalizes the runs, so the prompt run is
+     *    priced from its final counts.
      *
      * @param session The live realtime session the bridge owns (from `model.StartSession`).
      * @param input The same prep input used to build the session (carries AgentSessionID, TargetAgentID, …).
@@ -309,34 +411,126 @@ export class RealtimeClientSessionService {
      * @returns A {@link BridgeRealtimeRuntime} the bridge holds for the session lifetime.
      */
     async WireBridgeRealtimeSession(session, input, prep, contextUser, provider) {
+        this.reportBridgedAvatarStatus(session, input, prep);
         const coAgent = prep.CoAgent;
         const resolution = prep.Resolution;
         if (!coAgent || !resolution) {
             // Prep must have succeeded before wiring; degrade to a tool-error fallback rather than throw.
             return this.wireBridgeFallbackRuntime(session);
         }
+        // The delegation set the model may reach, narrowed to what THIS run-as user may run (the browser path
+        // applies the same filter; without it a bridged call would reach colleagues the caller cannot).
+        const allowedAgents = await FilterAllowedAgentsByCanRun(prep.EffectiveConfig?.realtime?.allowedAgents, contextUser);
+        // Spoken progress while delegated work runs — the same pacing/wording the generic session runner uses.
+        const narrator = new DelegationNarrator({
+            GetSession: () => session,
+            NarrationInstructionsTemplate: this.resolveNarrationInstructionsTemplate(),
+            NarrationPaceMs: GetNarrationPaceMs(prep.EffectiveConfig) ?? undefined,
+        });
+        let localToolHandler;
         const promptID = this.resolveCoAgentSystemPrompt(coAgent).PromptID;
         const obs = await this.createCoAgentObservabilityRun(coAgent, promptID, resolution.ModelID, resolution.VendorID, input.UserID || contextUser?.ID, input.AgentSessionID, contextUser, provider, input.ConversationID);
-        let finalized = false;
-        const finalize = async (success) => {
-            if (finalized) {
-                return;
-            }
-            finalized = true;
-            await this.FinalizeCoAgentRun(obs?.CoAgentRunID ?? null, obs?.PromptRunID ?? null, contextUser, provider, success, obs?.CoAgentRunStepID ?? null);
+        const usage = this.wireBridgeUsage(session, obs?.PromptRunID, contextUser, provider);
+        const finalize = this.createBridgeFinalizer(obs, usage, contextUser, provider);
+        this.wireBridgeToolCalls(session, {
+            Input: input,
+            Prep: prep,
+            ParentRunID: obs?.CoAgentRunID,
+            AllowedAgents: allowedAgents,
+            Narrator: narrator,
+            LocalToolHandler: () => localToolHandler,
+            ContextUser: contextUser,
+            Provider: provider,
+        });
+        this.finalizeOnBridgeClose(session, narrator, finalize, obs?.PromptRunID);
+        const runtime = {
+            CoAgentRunID: obs?.CoAgentRunID,
+            PromptRunID: obs?.PromptRunID,
+            Finalize: finalize,
+            CancelInFlightDelegations: () => {
+                narrator.Cancel(); // a stale "still working on it" line must not be spoken over the caller
+                return this.CancelInFlightDelegations(input.AgentSessionID);
+            },
+            CancelPendingNarration: () => narrator.Cancel(),
+            SetLocalToolHandler: (handler) => { localToolHandler = handler; },
+            WatchesMeetingVideo: GetWatchesMeetingVideo(prep.EffectiveConfig),
         };
-        // Tool calls → the shared delegation entry point, then hand the serialized result back to the model.
+        bridgeRuntimes.set(session, runtime);
+        return runtime;
+    }
+    /**
+     * Gives a bridged session the avatar status its driver had nothing to say about ({@link ResolveBridgedAvatarStatus}),
+     * with one log line: a prep that asked the driver for no avatar (a phone call, no face for the model's vendor, an
+     * unknown avatar, a Video/Output row that turns video off) leaves the driver nothing to report, and a driver that
+     * renders no avatar ignores a request and reports nothing. A host reads it like any driver's status (the LiveKit room
+     * puts it on the agent's bot, so the room shows its notice). A status the driver reported stands.
+     */
+    reportBridgedAvatarStatus(session, input, prep) {
+        const model = prep.Resolution;
+        const status = ResolveBridgedAvatarStatus({
+            Resolution: prep.AvatarResolution,
+            RoomDelivery: input.AvatarDelivery === 'room',
+            ModelShowsAvatar: () => (model ? RealtimeModelShowsAvatar(model, AIEngine.Instance) : false),
+            DriverStatus: session.AvatarStatus,
+        });
+        if (!status || status === session.AvatarStatus) {
+            return;
+        }
+        session.AvatarStatus = status;
+        const asked = prep.AvatarResolution?.Reason ? 'the driver was asked for none' : 'the driver was asked for one and reported nothing';
+        LogStatus(`[RealtimeCoAgent] bridged session avatar: audio only (${status.Reason}); ${asked}.`);
+    }
+    /**
+     * Records a bridged session's usage on its co-agent prompt run. The recorder is the session's only `OnUsage`
+     * subscriber: drivers keep one usage handler. Without a prompt run there is nowhere to record, so nothing subscribes
+     * and one line is logged, as the client-direct relay logs a dropped delta.
+     */
+    wireBridgeUsage(session, promptRunID, contextUser, provider) {
+        if (!promptRunID) {
+            LogStatus('WireBridgeRealtimeSession: the session has no co-agent prompt run, so its usage is not recorded.');
+            return undefined;
+        }
+        const recorder = new BridgeRealtimeUsageRecorder((write) => this.AccumulatePromptRunUsage(promptRunID, write.InputTokens, write.OutputTokens, contextUser, provider, write.Details), `prompt run ${promptRunID}`);
+        session.OnUsage((usage) => recorder.Add(usage));
+        return recorder;
+    }
+    /**
+     * The bridged session's finalizer. It closes the usage recorder first (no more updates; the unwritten usage is
+     * written), so the prompt run's cost, computed when finalize stamps `CompletedAt`, covers the whole session. On a
+     * graceful close it runs after the model session closed (see `finalizeOnBridgeClose`).
+     *
+     * It runs once, and every call returns the first call's promise: whichever path calls second (a `Close()` after a
+     * dropped connection's `OnClose` started the finalize) resolves only once the runs are finalized and priced. The
+     * first call decides the outcome (see {@link BridgeRealtimeRuntime.Finalize}).
+     */
+    createBridgeFinalizer(obs, usage, contextUser, provider) {
+        let finalizing;
+        const finalizeRuns = async (success, errorMessage) => {
+            await usage?.Close();
+            await this.FinalizeCoAgentRun(obs?.CoAgentRunID ?? null, obs?.PromptRunID ?? null, contextUser, provider, success, obs?.CoAgentRunStepID ?? null, errorMessage);
+        };
+        return (success, errorMessage) => {
+            finalizing ??= finalizeRuns(success, errorMessage);
+            return finalizing;
+        };
+    }
+    /** Tool calls → the host's local handler or the shared delegation entry point, then the result back to the model. */
+    wireBridgeToolCalls(session, wiring) {
         session.OnToolCall(async (call) => {
             try {
-                const result = await this.ExecuteRelayedTool({
-                    AgentSessionID: input.AgentSessionID,
-                    ParentRunID: obs?.CoAgentRunID,
-                    TargetAgentID: input.TargetAgentID,
-                    AllowedAgents: prep.EffectiveConfig?.realtime?.allowedAgents,
-                    DirectActions: prep.EffectiveConfig?.realtime?.directActions,
-                    Call: call,
-                }, contextUser, provider);
-                await session.SendToolResult(call.CallID, result.ResultJson);
+                const localHandler = wiring.LocalToolHandler();
+                const resultJson = localHandler?.Handles(call.ToolName)
+                    ? await localHandler.Execute(call)
+                    : (await wiring.Narrator.Track(() => this.ExecuteRelayedTool({
+                        AgentSessionID: wiring.Input.AgentSessionID,
+                        ParentRunID: wiring.ParentRunID,
+                        TargetAgentID: wiring.Input.TargetAgentID,
+                        AllowedAgents: wiring.AllowedAgents,
+                        DirectActions: wiring.Prep.EffectiveConfig?.realtime?.directActions,
+                        OnProgress: (progress) => wiring.Narrator.HandleProgress(progress),
+                        Call: call,
+                    }, wiring.ContextUser, wiring.Provider))).ResultJson;
+                await session.SendToolResult(call.CallID, resultJson);
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
@@ -344,15 +538,34 @@ export class RealtimeClientSessionService {
                 await session.SendToolResult(call.CallID, JSON.stringify({ success: false, error: message }));
             }
         });
-        // Finalize on graceful teardown (the bridge calls Close()) and on an unexpected drop. Both routed
-        // through the idempotent finalizer, so double-fire is harmless.
+    }
+    /**
+     * Finalizes on graceful teardown (the bridge calls `Close()`) and on an unexpected drop. Both go through the one
+     * finalizer, which runs once: a double fire finalizes once, and a `Close()` after a drop waits for the finalize the
+     * drop started, so it resolves only once the runs are finalized. Both finalize as completed: a host whose bridge
+     * start failed calls {@link BridgeRealtimeRuntime.Finalize} with `false` and the start's error before it closes the
+     * session.
+     *
+     * `Close()` closes the model session before it finalizes: a session reports its last usage while it closes (a
+     * Gemini avatar session, the seconds of video not reported yet), and the finalizer stores only what was reported
+     * before it ran. The close is waited for up to {@link BRIDGE_SESSION_CLOSE_WAIT_MS}. The runs are finalized whether
+     * the close finished, failed or is still running; a failed close still rejects, after the finalize.
+     *
+     * @param promptRunID The session's co-agent prompt run, which names the session in a log line.
+     */
+    finalizeOnBridgeClose(session, narrator, finalize, promptRunID) {
         const originalClose = session.Close.bind(session);
+        const label = promptRunID ? `prompt run ${promptRunID}` : 'a session with no co-agent prompt run';
         session.Close = async () => {
-            await finalize(true);
-            await originalClose();
+            narrator.Cancel(); // nothing more is spoken on a session that is closing
+            try {
+                await closeBridgedSessionWithin(originalClose, BRIDGE_SESSION_CLOSE_WAIT_MS, label);
+            }
+            finally {
+                await finalize(true);
+            }
         };
         session.OnClose?.(() => { void finalize(true); });
-        return { CoAgentRunID: obs?.CoAgentRunID, PromptRunID: obs?.PromptRunID, Finalize: finalize };
     }
     /**
      * Degenerate {@link BridgeRealtimeRuntime} for the rare case wiring is attempted without a resolved
@@ -363,7 +576,15 @@ export class RealtimeClientSessionService {
         session.OnToolCall((call) => {
             void session.SendToolResult(call.CallID, JSON.stringify({ success: false, error: 'Tool execution is unavailable — the co-agent did not resolve. Let the user know.' }));
         });
-        return { Finalize: async () => { } };
+        const runtime = {
+            Finalize: async () => { },
+            CancelInFlightDelegations: () => 0,
+            CancelPendingNarration: () => { },
+            SetLocalToolHandler: () => { },
+            WatchesMeetingVideo: false,
+        };
+        bridgeRuntimes.set(session, runtime);
+        return runtime;
     }
     /**
      * **The single source of truth for realtime session prep.** Builds the {@link RealtimeSessionParams}
@@ -397,13 +618,157 @@ export class RealtimeClientSessionService {
         const targetAgent = this.resolveTargetAgent(input.TargetAgentID);
         const appSettingsJson = await this.resolveAppRealtimeOverrides(input.ApplicationID, contextUser, provider);
         const effectiveConfig = this.resolveEffectiveConfig(coAgent, input.ConfigOverridesJson, targetAgent, appSettingsJson);
+        this.logDeprecatedVideoKeys(effectiveConfig, coAgent, targetAgent);
         const outcome = await this.resolveModelForSession(input, coAgent, effectiveConfig);
         if (!outcome.Resolution) {
             return { Success: false, ErrorMessage: outcome.ErrorMessage ?? this.noModelMessage() };
         }
         const resolution = outcome.Resolution;
-        const sessionParams = await this.buildSessionParams(input, coAgent, resolution.APIName, contextUser, provider, effectiveConfig, resolution.DriverClass, resolution.ModelID, resolution.ModelVendorID);
-        return { Success: true, CoAgent: coAgent, Resolution: resolution, EffectiveConfig: effectiveConfig, SessionParams: sessionParams };
+        let hostTools = input.HostTools;
+        if (input.ResolveHostTools) {
+            const dynamicHostTools = input.ResolveHostTools({
+                ModelID: resolution.ModelID,
+                ModelVendorID: resolution.ModelVendorID,
+                DriverClass: resolution.DriverClass,
+            });
+            if (dynamicHostTools !== undefined) {
+                hostTools = dynamicHostTools;
+            }
+        }
+        const effectiveInput = hostTools !== input.HostTools ? { ...input, HostTools: hostTools } : input;
+        // One answer for the whole session: it lowers channel exposure here and keeps the driver from
+        // turning on provider features that store session data (Gemini session resumption).
+        const zeroDataRetention = this.modelHasZeroDataRetention(resolution.ModelID, resolution.ModelVendorID);
+        // Channel scoping + client-tool tiers: narrows the declared tools to the scope's decision and
+        // folds the app tier into the capability manifest the prompt renders. The scoped input is what
+        // the prompt/tool builders see, so a vetoed channel is absent from the framing as well as the tools.
+        const scoped = await this.scopeSessionInput(effectiveInput, effectiveConfig, contextUser, provider, zeroDataRetention);
+        // A session nobody would see an avatar in (a phone call, an app without agent video) asks the driver for none
+        // and keeps the persona's voice.
+        const avatar = WithoutUnseenAvatar(this.ResolveSessionAvatar(scoped.Input, coAgent, effectiveConfig, resolution.ModelID, resolution.ModelVendorID), scoped.Input);
+        const sessionParams = {
+            ...(await this.buildSessionParams(scoped.Input, coAgent, resolution.APIName, contextUser, provider, effectiveConfig, resolution.DriverClass, resolution.ModelID, resolution.ModelVendorID, avatar)),
+            ZeroDataRetention: zeroDataRetention,
+        };
+        return {
+            Success: true, CoAgent: coAgent, Resolution: resolution, EffectiveConfig: effectiveConfig, SessionParams: sessionParams,
+            ClientPolicy: scoped.ClientPolicy, AvatarResolution: avatar,
+        };
+    }
+    /**
+     * Applies channel scoping and the client-tool tiers to a prepare input.
+     *
+     * - **App tier into the prompt.** `Application.AgentSettings.ClientTools` is resolved to metadata
+     *   and layered, through the unified {@link ResolveClientTools}, beneath the live surface's own
+     *   manifest in the app-context snapshot — so the co-agent is told about tools the app declares
+     *   even when the active surface did not republish them. (Only the HOST can run them; the browser
+     *   reports "declared but not registered" for one it has no handler for.) The agent's static
+     *   junction tools are deliberately NOT added to the voice prompt — voice prompts are
+     *   token-sensitive and a tool with no browser handler is noise — but they ride the returned policy
+     *   so the browser can describe them.
+     * - **Channel scoping.** When the browser reported candidates, they are scoped against the
+     *   registry and the cascade's `channels` section, and the declared tools narrowed to match
+     *   ({@link BuildSessionChannelPolicy}).
+     *
+     * @returns The (possibly adjusted) input, and the policy to hand back when candidates were reported.
+     */
+    async scopeSessionInput(input, effectiveConfig, contextUser, provider, modelHasZeroDataRetention = false) {
+        const tiers = await this.resolveSessionClientToolTiers(input.ApplicationID, input.TargetAgentID, contextUser);
+        const appContext = this.withAppToolTier(input.AppContext, tiers.App, input.TargetAgentID);
+        const candidates = input.ChannelCandidates ?? [];
+        if (candidates.length === 0) {
+            return { Input: appContext === input.AppContext ? input : { ...input, AppContext: appContext } };
+        }
+        const outcome = BuildSessionChannelPolicy({
+            Candidates: candidates,
+            ChannelsConfig: effectiveConfig.realtime?.channels ?? null,
+            Registry: this.readChannelRegistry(provider),
+            ClientTools: input.ExtraTools,
+            ClientToolTiers: tiers,
+            ModelHasZeroDataRetention: modelHasZeroDataRetention,
+        });
+        return {
+            Input: { ...input, ExtraTools: outcome.ClientTools, AppContext: appContext },
+            ClientPolicy: outcome.Policy,
+        };
+    }
+    /**
+     * Whether the session model's effective catalog configuration (type < model < vendor < model-vendor)
+     * declares `Privacy.ZeroDataRetention: true`. Fails closed: a model or vendor row that cannot be
+     * resolved, or a catalog lookup that throws, reads as "not declared", so an agent that REQUIRES zero
+     * data retention loses exposure rather than gaining it. Overridable seam.
+     *
+     * @param modelID The resolved `MJ: AI Models` id.
+     * @param modelVendorID The resolved model-vendor row id (the cascade's most specific layer).
+     */
+    modelHasZeroDataRetention(modelID, modelVendorID) {
+        if (!modelID) {
+            return false;
+        }
+        try {
+            return IsZeroDataRetention(AIEngine.Instance.GetEffectiveModelConfiguration(modelID, modelVendorID));
+        }
+        catch (error) {
+            LogError(`RealtimeClientSessionService.modelHasZeroDataRetention failed for model '${modelID}': ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    }
+    /**
+     * Layers the app's client tools beneath the surface's manifest in the app-context snapshot, through
+     * the unified resolver (`session > app`, first match by name wins). Returns the SAME snapshot object
+     * when nothing changes, so callers can detect "no change" by identity.
+     */
+    withAppToolTier(appContext, appTools, targetAgentId) {
+        if (!appContext || !appTools || appTools.length === 0) {
+            return appContext;
+        }
+        const surfaceTools = appContext.Capabilities?.Tools;
+        const tools = ResolveClientTools({ agentId: targetAgentId, sessionTools: surfaceTools, appTools: [...appTools] });
+        if (surfaceTools && tools.length === surfaceTools.length) {
+            return appContext; // the surface already covered every app tool
+        }
+        return { ...appContext, Capabilities: { ...appContext.Capabilities, Tools: tools } };
+    }
+    /**
+     * The server's view of the channel registry (`MJ: AI Agent Channels`), read from the request
+     * provider's cached {@link AIEngineBase} rows (already configured by the prepare). Overridable seam.
+     * Tolerant: an unloaded cache yields an empty registry (every candidate then reads as having no
+     * row), never a throw.
+     */
+    readChannelRegistry(provider) {
+        try {
+            const engine = AIEngineBase.GetProviderInstance(provider, AIEngineBase);
+            return (engine.AgentChannels ?? []).map(c => ({ Name: c.Name, IsActive: c.IsActive }));
+        }
+        catch (error) {
+            LogError(`RealtimeClientSessionService.readChannelRegistry failed: ${error instanceof Error ? error.message : String(error)}`);
+            return [];
+        }
+    }
+    /**
+     * Resolves the client-tool tiers the browser is told about at mint: the APP tier
+     * (`Application.AgentSettings.ClientTools` resolved against the tool-definition catalog) and the
+     * STATIC tier (the target agent's `MJ: AI Agent Client Tools` junction). Overridable seam; tolerant —
+     * any failure yields empty tiers and never fails the mint.
+     */
+    async resolveSessionClientToolTiers(applicationId, targetAgentId, contextUser) {
+        const tiers = {};
+        try {
+            const settings = await this.loadAppAgentSettings(applicationId, contextUser);
+            const definitions = AIEngine.Instance.ClientToolDefinitions ?? [];
+            const app = ResolveAppClientToolMetadata(settings?.ClientTools, definitions, ref => LogStatus(`RealtimeClientSessionService: the app's client tool '${ref.Name ?? ref.ClientToolDefinitionID}' matches no tool definition — skipping it.`));
+            if (app.length > 0) {
+                tiers.App = app;
+            }
+            const stat = targetAgentId ? AIEngine.Instance.GetClientToolsForAgent(targetAgentId).map(ClientToolMetadataFromDefinition) : [];
+            if (stat.length > 0) {
+                tiers.Static = stat;
+            }
+        }
+        catch (error) {
+            LogError(`RealtimeClientSessionService.resolveSessionClientToolTiers failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        return tiers;
     }
     /**
      * Resolves the EFFECTIVE realtime configuration via the surface-agnostic precedence cascade:
@@ -422,6 +787,27 @@ export class RealtimeClientSessionService {
     resolveEffectiveConfig(coAgent, overridesJson, targetAgent, appSettingsJson) {
         return ResolveEffectiveRealtimeConfig(this.getAgentTypeDefaultConfiguration(coAgent), coAgent.TypeConfiguration ?? null, overridesJson ?? null, targetAgent?.TypeConfiguration ?? null, appSettingsJson ?? null);
     }
+    /**
+     * Logs one line, once per co-agent and target pair per process, when the effective configuration sets
+     * `realtime.video.provider` or `realtime.video.providers`. Both are deprecated and nothing reads them, so an author
+     * who set them would otherwise get nothing and no word of it.
+     *
+     * @param config The effective configuration.
+     * @param coAgent The co-agent.
+     * @param targetAgent The voiced agent, when there is one.
+     */
+    logDeprecatedVideoKeys(config, coAgent, targetAgent) {
+        const keys = FindDeprecatedRealtimeVideoKeys(config);
+        const pair = `${NormalizeUUID(coAgent.ID)}|${NormalizeUUID(targetAgent?.ID)}`;
+        if (keys.length === 0 || deprecatedVideoKeysLogged.has(pair)) {
+            return;
+        }
+        deprecatedVideoKeysLogged.add(pair);
+        const voiced = targetAgent && !UUIDsEqual(targetAgent.ID, coAgent.ID) ? `'${targetAgent.Name}' (co-agent '${coAgent.Name}')` : `'${coAgent.Name}'`;
+        const what = keys.length === 1 ? `${keys[0]}, which is deprecated and does nothing` : `${keys.join(' and ')}, which are deprecated and do nothing`;
+        LogStatus(`[RealtimeCoAgent] The realtime configuration for ${voiced} sets ${what}. Choose the model with ` +
+            "realtime.modelPreference, and set an avatar's settings on its persona's Video binding (VendorSettings.Avatar).");
+    }
     /**
      * Resolves the APP cascade layer JSON from `Application.AgentSettings`: the `Realtime` overrides
      * (persona/disclosure/model) plus `RelevantAgents` mapped to the union-accumulated allowed-agent
@@ -438,6 +824,30 @@ export class RealtimeClientSessionService {
     async resolveAppRealtimeOverrides(applicationId, contextUser, 
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     provider) {
+        const settings = await this.loadAppAgentSettings(applicationId, contextUser);
+        if (!settings) {
+            return null;
+        }
+        const relevantAgents = (settings.RelevantAgents ?? []).map(r => {
+            const entry = { agentId: r.AgentID };
+            if (r.Label) {
+                entry.label = r.Label;
+            }
+            if (r.Disclosure === 'silent' || r.Disclosure === 'mention' || r.Disclosure === 'hand-voice') {
+                entry.disclosure = r.Disclosure;
+            }
+            return entry;
+        });
+        return BuildAppRealtimeOverridesJson(settings.Realtime ?? null, relevantAgents);
+    }
+    /**
+     * Reads and parses an application's `AgentSettings` (one tiny by-ID read, served from the provider's
+     * RunView cache on repeat). The RAW column is parsed with {@link ParseAgentSettings} rather than read
+     * through the CodeGen-generated `AgentSettingsObject` accessor, so a field added to the settings
+     * interface works the moment the code reading it ships, before CodeGen next refreshes the copy.
+     * Tolerant — a blank id, a failed read, a missing app, or an app with no usable settings returns `null`.
+     */
+    async loadAppAgentSettings(applicationId, contextUser) {
         const appId = applicationId?.trim();
         if (!appId) {
             return null;
@@ -453,24 +863,10 @@ export class RealtimeClientSessionService {
             if (!result.Success || !result.Results || result.Results.length === 0) {
                 return null;
             }
-            const settings = result.Results[0].AgentSettingsObject;
-            if (!settings) {
-                return null;
-            }
-            const relevantAgents = (settings.RelevantAgents ?? []).map(r => {
-                const entry = { agentId: r.AgentID };
-                if (r.Label) {
-                    entry.label = r.Label;
-                }
-                if (r.Disclosure === 'silent' || r.Disclosure === 'mention' || r.Disclosure === 'hand-voice') {
-                    entry.disclosure = r.Disclosure;
-                }
-                return entry;
-            });
-            return BuildAppRealtimeOverridesJson(settings.Realtime ?? null, relevantAgents);
+            return ParseAgentSettings(result.Results[0].AgentSettings);
         }
         catch (error) {
-            LogError(`RealtimeClientSessionService.resolveAppRealtimeOverrides failed for app '${appId}': ${error instanceof Error ? error.message : String(error)}`);
+            LogError(`RealtimeClientSessionService.loadAppAgentSettings failed for app '${appId}': ${error instanceof Error ? error.message : String(error)}`);
             return null;
         }
     }
@@ -544,11 +940,30 @@ export class RealtimeClientSessionService {
             run.UserID = userID;
         }
         if (await run.Save()) {
+            this.KeepCoAgentRunAlive(run.ID, provider, contextUser);
             return run.ID;
         }
         LogError(`RealtimeClientSessionService.createCoAgentRun save failed: ${run.LatestResult?.CompleteMessage ?? 'unknown error'}`);
         return null;
     }
+    /**
+     * Keeps a voice session's co-agent run alive as far as the {@link AgentRunWatchdog} is concerned. The
+     * run spans the whole call, but no agent loop owns it, so nothing stamped its heartbeat: the watchdog
+     * force-failed every call that ran past ~5 minutes ("no liveness heartbeat … owning process presumed
+     * dead") while the call carried on. Called when the run is created and again on each persisted
+     * session heartbeat (`SessionManager`), so whichever server instance the session is talking to keeps
+     * it fresh; the watchdog drops it once it is finalized. Only a database provider can stamp heartbeats —
+     * any other provider is a no-op, as for every agent run.
+     *
+     * @param coAgentRunID The session's co-agent run id (from its `Config`), or nothing.
+     * @param provider The request-scoped metadata provider.
+     * @param contextUser The user the heartbeat writes run as.
+     */
+    KeepCoAgentRunAlive(coAgentRunID, provider, contextUser) {
+        if (coAgentRunID && provider instanceof DatabaseProviderBase) {
+            AgentRunWatchdog.Instance.Track(coAgentRunID, provider, contextUser);
+        }
+    }
     /**
      * Creates the co-agent `AIPromptRun` row (Status `Running`) linked to the co-agent run via
      * `AgentRunID` AND to the co-agent itself via `AgentID` — so the run shows up both on the
@@ -626,11 +1041,59 @@ export class RealtimeClientSessionService {
      * @param provider The request-scoped metadata provider.
      * @param success Whether the session ended successfully (controls Completed vs Failed).
      * @param coAgentRunStepID The co-agent run's single `MJ: AI Agent Run Steps` row id, or `null` to skip.
+     * @param errorMessage Why the session failed (for example the bridge start's error), stamped as `ErrorMessage` on each
+     *   record it fails. Ignored when `success` is true. Without it the step gets a generic line and the runs none.
      */
-    async FinalizeCoAgentRun(coAgentRunID, promptRunID, contextUser, provider, success = true, coAgentRunStepID = null) {
-        await this.finalizeAgentRun(coAgentRunID, contextUser, provider, success);
-        await this.finalizePromptRun(promptRunID, contextUser, provider, success);
-        await this.finalizeRunStep(coAgentRunStepID, contextUser, provider, success);
+    async FinalizeCoAgentRun(coAgentRunID, promptRunID, contextUser, provider, success = true, coAgentRunStepID = null, errorMessage) {
+        const failure = success ? undefined : errorMessage?.trim() || undefined;
+        try {
+            await this.finalizeAgentRun(coAgentRunID, contextUser, provider, success, failure);
+            await this.finalizePromptRun(promptRunID, contextUser, provider, success, failure);
+            await this.finalizeRunStep(coAgentRunStepID, contextUser, provider, success, failure);
+        }
+        finally {
+            // Even when a finalize step throws, the run still owes its cost, and the watchdog must stop
+            // treating it as alive — or a run stuck at Running would be kept fresh indefinitely.
+            await this.rollUpCoAgentRunUsage(coAgentRunID, promptRunID, contextUser, provider);
+            if (coAgentRunID) {
+                AgentRunWatchdog.Instance.Untrack(coAgentRunID);
+            }
+        }
+    }
+    /**
+     * Copies the co-agent prompt run's tokens and cost onto the co-agent run. The realtime model's usage
+     * accumulates on the prompt run ({@link AccumulatePromptRunUsage}), which prices itself; the run's
+     * own `TotalCost` / `Total*TokensUsed` stayed 0, so everything that sums agent runs — the realtime
+     * analytics dashboard's per-session cost among them — left out the voice model entirely and showed
+     * only the delegated runs. Mirrors how an agent loop derives its run totals from its prompt runs.
+     *
+     * Applied whatever the run's status: a run the watchdog already failed, or one a shutdown cancelled,
+     * still owes its cost. Runs after {@link finalizePromptRun}, which waits for in-flight usage writes,
+     * so the copy sees the final counts. Tolerant: logs, never throws.
+     */
+    async rollUpCoAgentRunUsage(coAgentRunID, promptRunID, contextUser, provider) {
+        if (!coAgentRunID || !promptRunID) {
+            return;
+        }
+        try {
+            const promptRun = await provider.GetEntityObject('MJ: AI Prompt Runs', contextUser);
+            const run = await provider.GetEntityObject('MJ: AI Agent Runs', contextUser);
+            if (!(await promptRun.Load(promptRunID)) || !(await run.Load(coAgentRunID))) {
+                return;
+            }
+            const promptTokens = promptRun.TokensPrompt ?? 0;
+            const completionTokens = promptRun.TokensCompletion ?? 0;
+            run.TotalPromptTokensUsed = promptTokens;
+            run.TotalCompletionTokensUsed = completionTokens;
+            run.TotalTokensUsed = promptRun.TokensUsed ?? promptTokens + completionTokens;
+            run.TotalCost = promptRun.TotalCost ?? promptRun.Cost ?? 0;
+            if (run.Dirty && !(await run.Save())) {
+                LogError(`RealtimeClientSessionService.rollUpCoAgentRunUsage save failed: ${run.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+            }
+        }
+        catch (error) {
+            LogError(`RealtimeClientSessionService.rollUpCoAgentRunUsage failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
     }
     /**
      * Finalizes the **co-agent observability run(s)** for an agent session that were left `Running` because
@@ -717,8 +1180,11 @@ export class RealtimeClientSessionService {
         }
         return { PromptRunID: promptRuns.Results[0]?.ID ?? null, StepID: stepID };
     }
-    /** Loads + finalizes the co-agent `AIAgentRun` if still `Running`. Tolerant: logs, never throws. */
-    async finalizeAgentRun(coAgentRunID, contextUser, provider, success) {
+    /**
+     * Loads + finalizes the co-agent `AIAgentRun` if still `Running`, with `failure` as its `ErrorMessage` when it fails.
+     * Tolerant: logs, never throws.
+     */
+    async finalizeAgentRun(coAgentRunID, contextUser, provider, success, failure) {
         if (!coAgentRunID) {
             return;
         }
@@ -729,16 +1195,20 @@ export class RealtimeClientSessionService {
         run.Status = success ? 'Completed' : 'Failed';
         run.CompletedAt = new Date();
         run.Success = success;
+        if (failure) {
+            run.ErrorMessage = failure;
+        }
         if (!(await run.Save())) {
             LogError(`RealtimeClientSessionService.finalizeAgentRun save failed: ${run.LatestResult?.CompleteMessage ?? 'unknown error'}`);
         }
     }
     /**
      * Loads + finalizes the co-agent run's single system-prompt `MJ: AI Agent Run Steps` row if
-     * still `Running` (Status `Completed`/`Failed`, `CompletedAt`, `Success`). Tolerant: a
-     * missing/already-finalized step is a no-op; a load/save failure is logged, never thrown.
+     * still `Running` (Status `Completed`/`Failed`, `CompletedAt`, `Success`; a failed step's `ErrorMessage` is
+     * `failure`, or a generic line without one). Tolerant: a missing/already-finalized step is a no-op; a
+     * load/save failure is logged, never thrown.
      */
-    async finalizeRunStep(coAgentRunStepID, contextUser, provider, success) {
+    async finalizeRunStep(coAgentRunStepID, contextUser, provider, success, failure) {
         if (!coAgentRunStepID) {
             return;
         }
@@ -751,7 +1221,7 @@ export class RealtimeClientSessionService {
             step.CompletedAt = new Date();
             step.Success = success;
             if (!success) {
-                step.ErrorMessage = 'The realtime session ended in an error state.';
+                step.ErrorMessage = failure ?? 'The realtime session ended in an error state.';
             }
             if (!(await step.Save())) {
                 LogError(`RealtimeClientSessionService.finalizeRunStep save failed: ${step.LatestResult?.CompleteMessage ?? 'unknown error'}`);
@@ -761,8 +1231,11 @@ export class RealtimeClientSessionService {
             LogError(`RealtimeClientSessionService.finalizeRunStep failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
-    /** Loads + finalizes the co-agent `AIPromptRun` if still `Running`. Tolerant: logs, never throws. */
-    async finalizePromptRun(promptRunID, contextUser, provider, success) {
+    /**
+     * Loads + finalizes the co-agent `AIPromptRun` if still `Running`, with `failure` as its `ErrorMessage` when it fails.
+     * Tolerant: logs, never throws.
+     */
+    async finalizePromptRun(promptRunID, contextUser, provider, success, failure) {
         if (!promptRunID) {
             return;
         }
@@ -776,6 +1249,9 @@ export class RealtimeClientSessionService {
             run.Status = success ? 'Completed' : 'Failed';
             run.CompletedAt = new Date();
             run.Success = success;
+            if (failure) {
+                run.ErrorMessage = failure;
+            }
             if (!(await run.Save())) {
                 LogError(`RealtimeClientSessionService.finalizePromptRun save failed: ${run.LatestResult?.CompleteMessage ?? 'unknown error'}`);
             }
@@ -839,12 +1315,19 @@ export class RealtimeClientSessionService {
      * high-frequency usage checkpoint never overwrites freshly-appended transcript turns (and vice-versa).
      * Best-effort: load/save failures log and return `false`, never throw.
      *
+     * The per-modality details add into the usage record the run keeps in `ModelSpecificResponseDetails`
+     * (`RealtimeUsage.Input` / `.Output`, which pricing reads at finalize); every other key there is kept. The
+     * stored output video seconds never exceed the run's elapsed time plus 30 seconds, and the stored output video
+     * tokens never exceed 6,192 a second of that: usage is client-reported, and avatar video carries a price, per
+     * minute or per token.
+     *
      * @param promptRunID The co-agent observability prompt run.
      * @param inputDelta Input-token delta to add (caller clamps to >= 0).
      * @param outputDelta Output-token delta to add (caller clamps to >= 0).
+     * @param details Per-modality usage to add (input and output blocks, avatar video seconds included).
      * @returns `true` when the accumulated usage was persisted.
      */
-    async AccumulatePromptRunUsage(promptRunID, inputDelta, outputDelta, contextUser, provider) {
+    async AccumulatePromptRunUsage(promptRunID, inputDelta, outputDelta, contextUser, provider, details) {
         return this.serializePromptRunWrite(promptRunID, async () => {
             try {
                 const promptRun = await provider.GetEntityObject('MJ: AI Prompt Runs', contextUser);
@@ -855,6 +1338,9 @@ export class RealtimeClientSessionService {
                 promptRun.TokensPrompt = (promptRun.TokensPrompt ?? 0) + inputDelta;
                 promptRun.TokensCompletion = (promptRun.TokensCompletion ?? 0) + outputDelta;
                 promptRun.TokensUsed = (promptRun.TokensPrompt ?? 0) + (promptRun.TokensCompletion ?? 0);
+                if (details) {
+                    this.mergeUsageDetails(promptRun, details);
+                }
                 if (!(await promptRun.Save())) {
                     LogError(`AccumulatePromptRunUsage: prompt run ${promptRunID} save failed: ${promptRun.LatestResult?.CompleteMessage ?? 'unknown error'}`);
                     return false;
@@ -867,6 +1353,37 @@ export class RealtimeClientSessionService {
             }
         });
     }
+    /**
+     * Adds relayed per-modality usage into the run's usage record, with the output video seconds capped at the run's
+     * elapsed time plus {@link VIDEO_SECONDS_GRACE}, and the output video tokens at that many seconds of
+     * {@link VIDEO_TOKENS_PER_SECOND}. Details that are not a JSON object are left alone (logged).
+     */
+    mergeUsageDetails(promptRun, details) {
+        const runAt = promptRun.RunAt ? new Date(promptRun.RunAt).getTime() : Number.NaN;
+        const elapsedSeconds = Math.max(0, (Date.now() - runAt) / 1000);
+        const maxVideoSeconds = Number.isFinite(elapsedSeconds) ? elapsedSeconds + VIDEO_SECONDS_GRACE : undefined;
+        const merged = MergeRealtimeUsageRecord(promptRun.ModelSpecificResponseDetails, details, {
+            MaxOutputVideoSeconds: maxVideoSeconds,
+            MaxOutputVideoTokens: maxVideoSeconds === undefined ? undefined : maxVideoSeconds * VIDEO_TOKENS_PER_SECOND,
+        });
+        if (!merged) {
+            LogError(`AccumulatePromptRunUsage: prompt run ${promptRun.ID} has details that are not a JSON object — usage details dropped.`);
+            return;
+        }
+        this.logClampedVideo(promptRun.ID, merged);
+        promptRun.ModelSpecificResponseDetails = merged.Details;
+    }
+    /** One log line for each output video quantity the merge capped. */
+    logClampedVideo(promptRunID, merged) {
+        if (merged.ClampedVideoSeconds > 0) {
+            LogStatus(`AccumulatePromptRunUsage: prompt run ${promptRunID} reported ${merged.ClampedVideoSeconds} s more avatar video than ` +
+                `the run's elapsed time plus ${VIDEO_SECONDS_GRACE} s allows; the stored seconds are capped.`);
+        }
+        if (merged.ClampedVideoTokens > 0) {
+            LogStatus(`AccumulatePromptRunUsage: prompt run ${promptRunID} reported ${merged.ClampedVideoTokens} more avatar video tokens than ` +
+                `${VIDEO_TOKENS_PER_SECOND} a second of the run's elapsed time plus ${VIDEO_SECONDS_GRACE} s allows; the stored tokens are capped.`);
+        }
+    }
     /** Parses the prompt run's `Messages` JSON into a mutable chat-message array (tolerant: `[]` on empty/malformed). */
     parsePromptRunMessages(raw) {
         if (!raw || !raw.trim()) {
@@ -1030,12 +1547,19 @@ export class RealtimeClientSessionService {
      *   {@link resolveConfiguredModelPreference}. METADATA preferences degrade gracefully — an
      *   unsatisfiable preference logs and FALLS THROUGH to the default (mirroring the co-agent
      *   resolution chain's tolerant metadata steps), it never breaks calls.
-     * - Without either: the existing default behavior via {@link resolveRealtimeModel}
-     *   (highest-PowerRank active Realtime model), with the generic {@link noModelMessage} on failure.
+     * - Without either: the default walk ({@link resolveDefaultRealtimeModel}): for a co-agent with video on, in a session
+     *   that could show an avatar (a browser session, or a server-side one with {@link PrepareClientSessionInput.AvatarDelivery}
+     *   `'room'`), the first candidate that shows one ({@link ResolveAvatarRealtimeModel}); else the existing default via
+     *   {@link resolveRealtimeModel} (highest-PowerRank active Realtime model), with the generic
+     *   {@link noModelMessage} on failure. The two explicit choices above win over the video preference.
+     *
+     * On every path the chosen model's vendor follows whether the session will show an avatar (the video setting is on
+     * and the session could show one): among the model's keyed vendors, one that renders avatars (Vertex AI for Gemini
+     * 3.8 Live) only when it will, else one that renders none; see {@link resolveVendorAndInstantiate}.
      *
      * @param input The prepare-session input (carries the optional preferred model id).
      * @param coAgent The resolved co-agent (threaded to the default-resolution seam).
-     * @param effectiveConfig The resolved effective configuration (carries `modelPreference`).
+     * @param effectiveConfig The resolved effective configuration (carries `modelPreference` and the video setting).
      * @returns The resolution outcome (resolution or failure reason).
      */
     async resolveModelForSession(input, coAgent, effectiveConfig) {
@@ -1046,16 +1570,62 @@ export class RealtimeClientSessionService {
         // A resolver that fell back to the environment itself would answer before the seam, so a
         // subclass that overrides the seam would lose to AI_VENDOR_API_KEY__<driver>.
         const resolveRunKey = this.buildRunKeyResolver(input.APIKeys);
+        const scope = input.CredentialScope ?? 'Any';
+        const preferAvatar = effectiveConfig?.realtime?.video?.enabled === true && RealtimeSessionCanShowAvatar(input);
         if (input.PreferredModelID) {
-            return this.resolvePreferredRealtimeModel(input.PreferredModelID, resolveRunKey);
+            return this.resolvePreferredRealtimeModel(input.PreferredModelID, resolveRunKey, scope, preferAvatar);
         }
-        const fromConfig = this.resolveConfiguredModelPreference(effectiveConfig, resolveRunKey);
+        const fromConfig = this.resolveConfiguredModelPreference(effectiveConfig, resolveRunKey, scope, preferAvatar);
         if (fromConfig) {
             return { Resolution: fromConfig };
         }
-        const resolution = await this.resolveRealtimeModel(coAgent, resolveRunKey);
+        const resolution = await this.resolveDefaultRealtimeModel(coAgent, preferAvatar, resolveRunKey, scope);
         return resolution ? { Resolution: resolution } : { ErrorMessage: this.noModelMessage() };
     }
+    /**
+     * The default walk. With `preferAvatar` (the co-agent's video setting is on and the session could show an avatar),
+     * it takes the first candidate that shows one ({@link ResolveAvatarRealtimeModel}). When none does, or without it, it
+     * takes {@link resolveRealtimeModel}'s choice; when one was preferred, one log line says the call stays audio only.
+     */
+    async resolveDefaultRealtimeModel(coAgent, preferAvatar, resolve, credentialScope) {
+        const withAvatar = preferAvatar ? this.ResolveAvatarRealtimeModel(coAgent, resolve, credentialScope) : null;
+        if (withAvatar) {
+            return withAvatar;
+        }
+        const resolution = await this.resolveRealtimeModel(coAgent, resolve, credentialScope, preferAvatar);
+        if (preferAvatar && resolution) {
+            LogStatus('[RealtimeCoAgent] Video is on, but no realtime model with a usable key shows an avatar (its Video/Output row ' +
+                `and its endpoint): using '${resolution.ModelName ?? resolution.APIName}' on ${resolution.DriverClass ?? 'its driver'}, audio only.`);
+        }
+        return resolution;
+    }
+    /**
+     * For a co-agent with video on: the first candidate that shows an avatar and supports client-direct sessions, in the
+     * default walk's order (highest PowerRank first; a model's Active vendor rows by Priority, each with a usable key).
+     * A candidate shows an avatar when its model's Video/Output row allows video or it has none, and its driver renders
+     * avatars for the vendor's API name on its endpoint ({@link RealtimeModelShowsAvatar}). Every keyed vendor of a model
+     * is tried, not only the first. **Overridable seam.**
+     *
+     * @param coAgent The co-agent (reserved for future per-agent model preference).
+     * @param resolve The session's run-scoped key resolver (run keys only; see {@link resolveVendorAndInstantiate}).
+     * @param credentialScope The session's credential scope; see {@link resolveVendorAndInstantiate}.
+     * @returns The resolution, or `null` when no candidate shows an avatar.
+     */
+    ResolveAvatarRealtimeModel(coAgent, resolve, credentialScope = 'Any') {
+        const resolveKey = this.buildKeyChain(resolve, credentialScope);
+        for (const model of this.selectRealtimeModelCandidates(coAgent)) {
+            if (ReadRealtimeVideoOutputRow(model.ID, AIEngine.Instance) === 'unsupported') {
+                continue;
+            }
+            for (const vendor of ListRealtimeVendorsForModel(model.ID)) {
+                const resolution = this.instantiateRealtimeVendor(model, vendor, resolveKey);
+                if (resolution?.Model.SupportsClientDirect && RealtimeModelShowsAvatar(resolution, AIEngine.Instance)) {
+                    return resolution;
+                }
+            }
+        }
+        return null;
+    }
     /**
      * The session's run-scoped keys as a resolver: the key for a driver class when the run carries
      * one, else `undefined` — no platform fallback. The fallback belongs to
@@ -1077,9 +1647,11 @@ export class RealtimeClientSessionService {
      *
      * @param effectiveConfig The resolved effective configuration.
      * @param resolve The session's run-scoped key resolver (run keys only; see {@link resolveVendorAndInstantiate}).
+     * @param credentialScope The session's credential scope; see {@link resolveVendorAndInstantiate}.
+     * @param showsAvatar Whether the session will show an avatar; see {@link resolveVendorAndInstantiate}.
      * @returns The resolution, or `null` when no preference is configured or it can't be satisfied.
      */
-    resolveConfiguredModelPreference(effectiveConfig, resolve) {
+    resolveConfiguredModelPreference(effectiveConfig, resolve, credentialScope = 'Any', showsAvatar = false) {
         const preference = effectiveConfig?.realtime?.modelPreference;
         if (!preference) {
             return null;
@@ -1095,7 +1667,7 @@ export class RealtimeClientSessionService {
                 `'${model.Name}' but it is not an Active Realtime model — falling through to default resolution.`);
             return null;
         }
-        const resolution = this.resolveVendorAndInstantiate(model, resolve);
+        const resolution = this.resolveVendorAndInstantiate(model, resolve, credentialScope, showsAvatar);
         if (!resolution) {
             LogError(`RealtimeClientSessionService: configured realtime model preference '${model.Name}' has no usable ` +
                 'vendor DriverClass/API key — falling through to default resolution.');
@@ -1128,9 +1700,11 @@ export class RealtimeClientSessionService {
      *
      * @param preferredModelID The `MJ: AI Models.ID` the user chose.
      * @param resolve The session's run-scoped key resolver (run keys only; see {@link resolveVendorAndInstantiate}).
+     * @param credentialScope The session's credential scope; see {@link resolveVendorAndInstantiate}.
+     * @param showsAvatar Whether the session will show an avatar; see {@link resolveVendorAndInstantiate}.
      * @returns The resolution outcome (resolution or a specific failure reason).
      */
-    resolvePreferredRealtimeModel(preferredModelID, resolve) {
+    resolvePreferredRealtimeModel(preferredModelID, resolve, credentialScope = 'Any', showsAvatar = false) {
         const model = this.findModelByID(preferredModelID);
         if (!model) {
             return { ErrorMessage: `The requested realtime model (id '${preferredModelID}') was not found in AI model metadata.` };
@@ -1141,7 +1715,7 @@ export class RealtimeClientSessionService {
         if (!this.isRealtimeModel(model)) {
             return { ErrorMessage: `The requested model '${model.Name}' is not a Realtime model (its type is '${model.AIModelType}').` };
         }
-        const resolution = this.resolveVendorAndInstantiate(model, resolve);
+        const resolution = this.resolveVendorAndInstantiate(model, resolve, credentialScope, showsAvatar);
         if (!resolution) {
             return {
                 ErrorMessage: `The requested model '${model.Name}' has no active vendor with a usable DriverClass/API key ` +
@@ -1174,9 +1748,11 @@ export class RealtimeClientSessionService {
      *
      * @param coAgent The co-agent being voiced (reserved for future per-agent model preference).
      * @param resolve The session's run-scoped key resolver (run keys only; see {@link resolveVendorAndInstantiate}).
+     * @param credentialScope The session's credential scope; see {@link resolveVendorAndInstantiate}.
+     * @param showsAvatar Whether the session will show an avatar; see {@link resolveVendorAndInstantiate}.
      * @returns The resolved model + identifiers, or `null`.
      */
-    async resolveRealtimeModel(coAgent, resolve) {
+    async resolveRealtimeModel(coAgent, resolve, credentialScope = 'Any', showsAvatar = false) {
         // Walk candidates in descending PowerRank, returning the FIRST that fully resolves to a usable
         // client-direct driver (active vendor + API key + ClassFactory driver + SupportsClientDirect).
         // Single-pick dead-ended whenever the highest-power model lacked a key or client-direct support
@@ -1184,7 +1760,7 @@ export class RealtimeClientSessionService {
         // surfaced "No usable Realtime model" instead of falling through to a model that works.
         const candidates = this.selectRealtimeModelCandidates(coAgent);
         for (const model of candidates) {
-            const resolution = this.resolveVendorAndInstantiate(model, resolve);
+            const resolution = this.resolveVendorAndInstantiate(model, resolve, credentialScope, showsAvatar);
             if (resolution && resolution.Model.SupportsClientDirect) {
                 return resolution;
             }
@@ -1203,16 +1779,43 @@ export class RealtimeClientSessionService {
      * @param resolve The session's run-scoped key resolver. Expected to answer with run keys only:
      *   one that falls back to the environment itself answers before {@link getAPIKeyForDriver} and
      *   so bypasses an override of it.
+     * @param credentialScope A scope that rules out the `'Environment'` source (`'RuntimeOnly'`) drops the
+     *   {@link getAPIKeyForDriver} seam: the run's keys are the whole chain, so a vendor they do not key
+     *   is never selected on the platform's key.
+     * @param showsAvatar Whether the session will show an avatar. The highest-Priority keyed vendor stands when it
+     *   renders avatars ({@link RealtimeModelShowsAvatar}) exactly when the session will show one; otherwise the first
+     *   other keyed vendor that does is taken, when there is one. So a vendor that renders avatars (Vertex AI for Gemini
+     *   3.8 Live, with its own billing and limits) takes a session only when it will show an avatar, or when it is the
+     *   only keyed vendor; and a session that will show one goes to such a vendor whatever the Priority order.
      * @returns The full resolution, or `null` when no vendor/key/driver can be satisfied.
      */
-    resolveVendorAndInstantiate(model, resolve) {
-        // The run's keys first, then this service's own seam (which subclasses and tests override) —
-        // so a run-scoped credential wins without taking that seam away from anyone who replaced it.
-        const resolveKey = (driverClass) => resolve?.(driverClass) ?? this.getAPIKeyForDriver(driverClass);
+    resolveVendorAndInstantiate(model, resolve, credentialScope = 'Any', showsAvatar = false) {
+        const resolveKey = this.buildKeyChain(resolve, credentialScope);
         const vendor = this.selectRealtimeVendor(model.ID, resolveKey);
-        if (!vendor) {
-            return null;
-        }
+        const first = vendor ? this.instantiateRealtimeVendor(model, vendor, resolveKey) : null;
+        if (!vendor || !first) {
+            return first;
+        }
+        return ChooseRealtimeVendorForAvatar(vendor, first, ListRealtimeVendorsForModel(model.ID), showsAvatar, {
+            Instantiate: (other) => this.instantiateRealtimeVendor(model, other, resolveKey),
+            RendersAvatar: (resolution) => RealtimeModelShowsAvatar(resolution, AIEngine.Instance),
+            // A stand-in does client-direct sessions when the first one does.
+            Accepts: (resolution) => resolution.Model.SupportsClientDirect || !first.Model.SupportsClientDirect,
+        });
+    }
+    /**
+     * The session's complete key chain for vendor selection and the mint (see {@link resolveVendorAndInstantiate}): the
+     * run's keys first, then this service's own seam (which subclasses and tests override), so a run-scoped credential
+     * wins without taking that seam away from anyone who replaced it. A scope that rules out the environment has no second
+     * step: the seam's default is the platform key.
+     */
+    buildKeyChain(resolve, credentialScope) {
+        return CredentialScopeAllows(credentialScope, 'Environment')
+            ? (driverClass) => resolve?.(driverClass) ?? this.getAPIKeyForDriver(driverClass)
+            : (driverClass) => resolve?.(driverClass);
+    }
+    /** Instantiates a vendor's realtime driver with its key from the chain; `null` when the key or the driver is missing. */
+    instantiateRealtimeVendor(model, vendor, resolveKey) {
         const apiKey = resolveKey(vendor.DriverClass);
         if (!apiKey) {
             return null;
@@ -1257,7 +1860,9 @@ export class RealtimeClientSessionService {
     }
     /**
      * The active models of AIModelType `Realtime`, sorted highest-PowerRank first — the candidate
-     * list {@link resolveRealtimeModel} walks until one yields a usable client-direct driver.
+     * list {@link resolveRealtimeModel} walks until one yields a usable client-direct driver, and
+     * {@link ResolveAvatarRealtimeModel} walks first for a co-agent with video on. Equal PowerRanks
+     * keep the engine's cached order (a stable sort).
      * Returns ALL candidates (not just the top pick) so a keyless or non-client-direct top model
      * falls through to the next usable one instead of dead-ending the whole resolution.
      *
@@ -1308,20 +1913,24 @@ export class RealtimeClientSessionService {
      * @param driverClass The resolved vendor's DriverClass — matches per-provider voice settings.
      * @param modelID The resolved `MJ: AI Models` id — keys the model-catalog `ModelConfiguration` cascade.
      * @param modelVendorID The resolved `MJ: AI Model Vendors` ROW id — the cascade's most-specific layer.
+     * @param resolvedAvatar The session's avatar resolution, when the caller already made it; resolved here otherwise.
      * @returns The assembled session params.
      */
-    async buildSessionParams(input, coAgent, modelApiName, contextUser, provider, effectiveConfig, driverClass, modelID, modelVendorID) {
-        const directTools = this.BuildDirectActionTools(input.TargetAgentID, effectiveConfig, driverClass, input.AgentSessionID);
+    async buildSessionParams(input, coAgent, modelApiName, contextUser, provider, effectiveConfig, driverClass, modelID, modelVendorID, resolvedAvatar) {
+        const directTools = this.projectDirectActions(input, effectiveConfig, driverClass);
         const hasDirectTools = directTools.length > 0 || (input.ExtraTools != null && input.ExtraTools.length > 0);
         const systemPrompt = await this.buildCompanionSystemPrompt(input, coAgent, contextUser, provider, effectiveConfig, hasDirectTools);
         const memoryContext = await this.assembleMemoryContext(input, coAgent, contextUser, provider);
         const combinedExtra = directTools.length > 0
             ? [...(input.ExtraTools ?? []), ...directTools]
             : input.ExtraTools;
-        const tools = this.buildStableToolSet(combinedExtra);
+        const tools = this.appendHostTools(this.buildStableToolSet(combinedExtra), input.HostTools);
         // Hoisted (rather than built inline at the return) so the mint log below can report the voice
-        // that ACTUALLY reached the driver — see the `voice=` field. Same bag, built once.
-        const configBag = this.buildSessionConfigBag(input, effectiveConfig, driverClass, modelID, modelVendorID);
+        // that ACTUALLY reached the driver — see the `voice=` field. Same bag, built once. A phone call, or
+        // an app without agent video, carries no avatar request whoever resolved it (WithoutUnseenAvatar is
+        // idempotent).
+        const avatar = WithoutUnseenAvatar(resolvedAvatar ?? this.ResolveSessionAvatar(input, coAgent, effectiveConfig, modelID, modelVendorID), input);
+        const configBag = this.withAvatarVoice(this.buildSessionConfigBag(input, effectiveConfig, driverClass, modelID, modelVendorID), avatar, input);
         WarnOnUnmatchedProviderVoice(effectiveConfig, driverClass, 'RealtimeClientSessionService');
         // One line per mint: confirms which tools + whether the channel-direct framing actually reach
         // the model — settles "why does the co-agent delegate instead of calling browser_*" without
@@ -1330,6 +1939,7 @@ export class RealtimeClientSessionService {
         // actually reached the driver legible — the whole failure mode in #3530 was that it was not.
         console.log(`[RealtimeCoAgent] mint model=${modelApiName} driver=${driverClass ?? 'unknown'} ` +
             `voice=${typeof configBag?.['voice'] === 'string' ? configBag['voice'] : 'none'} ` +
+            `avatar=${avatar.Avatar ? avatar.Avatar.AvatarID : avatar.Reason ? `none(${avatar.Reason})` : 'none'} ` +
             `tools=[${tools.map(t => t.Name).join(', ')}] ` +
             `channelExceptionInPrompt=${systemPrompt.includes('interactive-surface')}`);
         return {
@@ -1344,8 +1954,58 @@ export class RealtimeClientSessionService {
             MaxSessionSeconds: input.MaxSessionSeconds,
             UserID: contextUser?.ID,
             HasToolFraming: true,
+            ...(avatar.Avatar ? { Avatar: input.AvatarDelivery ? { ...avatar.Avatar, Delivery: input.AvatarDelivery } : avatar.Avatar } : {}),
         };
     }
+    /**
+     * The live avatar this session asks for, if any: from the voiced agent's persona, or `realtime.video.avatarId`,
+     * when the agent's video setting is on (see `ResolveRealtimeAvatar`). A call that picked an avatar (its runtime
+     * override names `realtime.video.avatarId`) while that setting is off asks for none, with reason `video-off`. A model
+     * whose `MJ: AI Model Modalities`
+     * Video/Output row turns video off asks for none (reason `endpoint`, one log line); otherwise whether the session can
+     * render it is the driver's call. A seam so tests can supply a resolution without the engine's persona metadata.
+     *
+     * @param input The prepare-session input (the voiced agent).
+     * @param coAgent The co-agent.
+     * @param effectiveConfig The effective configuration.
+     * @param modelID The resolved model.
+     * @param modelVendorID The resolved model-vendor row; its vendor scopes the persona bindings.
+     */
+    ResolveSessionAvatar(input, coAgent, effectiveConfig, modelID, modelVendorID) {
+        const videoOn = effectiveConfig?.realtime?.video?.enabled === true;
+        const avatarPicked = !!ResolveEffectiveRealtimeConfig(null, null, input.ConfigOverridesJson).realtime?.video?.avatarId;
+        if (!modelID || (!videoOn && !avatarPicked)) {
+            return {};
+        }
+        const vendorID = modelVendorID ? AIEngine.Instance.ModelVendors.find((mv) => UUIDsEqual(mv.ID, modelVendorID))?.VendorID : undefined;
+        const videoOutputRow = ReadRealtimeVideoOutputRow(modelID, AIEngine.Instance);
+        if (videoOn && videoOutputRow === 'unsupported') {
+            LogStatus(`[RealtimeCoAgent] No avatar asked for: the Video/Output modality row of '${this.findModelByID(modelID)?.Name ?? modelID}' ` +
+                'turns video off (IsSupported false). The call is audio only. Reason: endpoint.');
+        }
+        return ResolveRealtimeAvatar({
+            EffectiveConfig: effectiveConfig,
+            TargetAgentID: input.TargetAgentID,
+            CoAgentID: coAgent.ID,
+            ModelID: modelID,
+            VendorID: vendorID,
+            VideoOutputRow: videoOutputRow,
+            AvatarPicked: avatarPicked,
+        }, AIEngine.Instance);
+    }
+    /**
+     * The config bag with the avatar persona's voice, so the face and the voice match, unless a voice was picked in this
+     * call (a runtime override's `realtime.voice.default.voice`), which wins. A session nobody would see the avatar in (a
+     * phone call, an app without agent video) keeps the voice without the face, so the agent sounds the same as in a call
+     * that shows it.
+     */
+    withAvatarVoice(bag, avatar, input) {
+        if (!avatar.Voice) {
+            return bag;
+        }
+        const picked = ResolveEffectiveRealtimeConfig(null, null, input.ConfigOverridesJson).realtime?.voice?.default?.voice;
+        return picked ? bag : { ...(bag ?? {}), voice: avatar.Voice };
+    }
     /**
      * Builds the provider-pact `Config` bag for the session: the effective config's resolved voice
      * settings (per {@link GetProviderVoiceSettings} — the persona's agnostic wire-level slots
@@ -1413,6 +2073,7 @@ export class RealtimeClientSessionService {
         const colleagues = this.buildColleaguesFromConfig(effectiveConfig, input.TargetAgentID);
         const framing = BuildRealtimeAgentFraming(targetName, this.buildInteractiveSurfaceFraming(input.ExtraTools), colleagues, hasDirectTools);
         const meetingFraming = this.buildMeetingFraming(input);
+        const hostFraming = input.HostFraming?.trim() ?? '';
         const coAgentPrompt = this.getCoAgentSystemPromptText(coAgent);
         const voiceManner = BuildVoiceMannerSection(effectiveConfig);
         const targetIdentity = this.formatTargetIdentity(target);
@@ -1420,7 +2081,7 @@ export class RealtimeClientSessionService {
         const priorTranscript = this.formatPriorTranscript(input.PriorTranscript);
         const history = this.formatConversationHistory(input.ConversationMessages);
         const memoryContext = await this.assembleMemoryContext(input, coAgent, contextUser, provider);
-        return [framing, meetingFraming, coAgentPrompt, voiceManner, targetIdentity, appContextSection, priorTranscript, history, memoryContext]
+        return [framing, meetingFraming, hostFraming, coAgentPrompt, voiceManner, targetIdentity, appContextSection, priorTranscript, history, memoryContext]
             .filter(part => part && part.trim().length > 0)
             .join('\n\n');
     }
@@ -1542,7 +2203,9 @@ export class RealtimeClientSessionService {
                 `Knowledge Hub" → ContextTool with action 'NavigateToApp'; "open this record"; "switch to the X tab"). ` +
                 `Do NOT route in-app navigation/actions through '${INVOKE_TARGET_AGENT_TOOL_NAME}', and NEVER say you ` +
                 `need an active session id or a screen snapshot to do them — calling 'ContextTool' is all that's ` +
-                `needed. Reserve '${INVOKE_TARGET_AGENT_TOOL_NAME}' for actual analysis / data work, not navigation.`;
+                `needed. Reserve '${INVOKE_TARGET_AGENT_TOOL_NAME}' for actual analysis / data work, not navigation. ` +
+                `When a channel note lists interactive channels you can use, 'ContextTool' also addresses ONE of ` +
+                `them: add "target": { "channel": "<channel name>" } and use that channel's action names.`;
         }
         return clause;
     }
@@ -1746,6 +2409,21 @@ export class RealtimeClientSessionService {
         }
         return result;
     }
+    /** Appends the host-declared tools to a stable tool set, dropping any whose name is already taken. */
+    appendHostTools(tools, hostTools) {
+        if (!hostTools || hostTools.length === 0) {
+            return tools;
+        }
+        const taken = new Set(tools.map((t) => t.Name.toLowerCase()));
+        const merged = [...tools];
+        for (const tool of hostTools) {
+            if (!taken.has(tool.Name.toLowerCase())) {
+                taken.add(tool.Name.toLowerCase());
+                merged.push(tool);
+            }
+        }
+        return merged;
+    }
     /**
      * Builds the {@link RealtimeToolBroker} for a relayed tool call, wiring `DelegateToTarget` to a
      * target-agent run and `ExecuteTool` to direct-action execution or a structured "not available" placeholder.
@@ -1934,11 +2612,13 @@ export class RealtimeClientSessionService {
     /**
      * Runs (or resumes) the target agent for a delegation. Threads the combined abort signal, parent
      * run linkage, session id, and the `OnProgress` callback so the resolver can stream progress.
+     * The browser session id becomes the run's `sessionID` (client-tool channel) and the app-context
+     * snapshot rides `data.appContext` (prompt context and surface tools); both are optional.
      * When {@link ExecuteRelayedToolInput.ResumeRunID} is set, resumes that paused run via
      * `lastRunId` + `autoPopulateLastRunPayload` (the user's answer continues the same interactive
      * run) instead of starting fresh.
      *
-     * @param input The relayed tool input (linkage, progress callback, optional resume id).
+     * @param input The relayed tool input (linkage, progress callback, optional resume id, browser session, app context).
      * @param request The broker's delegation request (call id + arguments + abort signal).
      * @param target The resolved target agent.
      * @param contextUser The calling user.
@@ -1961,6 +2641,8 @@ export class RealtimeClientSessionService {
             cancellationToken: this.combineSignals(request.AbortSignal, input.AbortSignal),
             parentRun: parentRun ?? undefined,
             agentSessionID: input.AgentSessionID,
+            sessionID: input.BrowserSessionID,
+            data: input.AppContext ? { appContext: input.AppContext } : undefined,
             onProgress: input.OnProgress,
             lastRunId: input.ResumeRunID,
             autoPopulateLastRunPayload: input.ResumeRunID ? true : undefined
@@ -2046,11 +2728,25 @@ export class RealtimeClientSessionService {
         const agentActions = (AIEngine.Instance.AgentActions ?? []).filter(aa => UUIDsEqual(aa.AgentID, targetAgentID) && aa.Status === 'Active');
         return (ActionEngineServer.Instance.Actions ?? []).filter(a => agentActions.some(aa => UUIDsEqual(aa.ActionID, a.ID)) && a.Status === 'Active');
     }
+    /**
+     * The session's direct-action tools. When the input excludes direct actions, none, and the empty
+     * projection is recorded so the session's relays run none.
+     */
+    projectDirectActions(input, effectiveConfig, driverClass) {
+        if (input.ExcludeDirectActions) {
+            this.recordEmptyProjection(input.AgentSessionID);
+            return [];
+        }
+        return this.BuildDirectActionTools(input.TargetAgentID, effectiveConfig, driverClass, input.AgentSessionID);
+    }
     /**
      * Builds the projected direct action tool definitions for a target agent if supported by the driver.
      * Gated by driver capability (`SupportsDynamicToolSet`) and explicit configuration opt-in
      * (`Configuration.realtime.directActions.enabled = true`).
      *
+     * With `agentSessionID`, the projection is recorded for the session, even when it is empty: relayed
+     * direct-action calls for the session may run only the projected actions.
+     *
      * @param targetAgentID The target agent ID being voiced.
      * @param effectiveConfig The resolved effective configuration.
      * @param driverClass The resolved vendor's DriverClass.
@@ -2058,10 +2754,12 @@ export class RealtimeClientSessionService {
      */
     BuildDirectActionTools(targetAgentID, effectiveConfig, driverClass, agentSessionID) {
         if (!targetAgentID || !this.driverSupportsDynamicToolSet(driverClass)) {
+            this.recordEmptyProjection(agentSessionID);
             return [];
         }
         const directConfig = GetDirectActionsConfig(effectiveConfig);
         if (!directConfig || !directConfig.enabled) {
+            this.recordEmptyProjection(agentSessionID);
             return [];
         }
         const candidateActions = this.getTargetAgentActions(targetAgentID);
@@ -2080,6 +2778,12 @@ export class RealtimeClientSessionService {
         }
         return tools;
     }
+    /** Records that a session projected no direct actions, so its relays run none. */
+    recordEmptyProjection(agentSessionID) {
+        if (agentSessionID) {
+            this.sessionWireActionMaps.Set(agentSessionID, new Map());
+        }
+    }
     /** @deprecated Use {@link BuildDirectActionTools}. */
     buildDirectActionTools(targetAgentID, effectiveConfig, driverClass, agentSessionID) {
         return this.BuildDirectActionTools(targetAgentID, effectiveConfig, driverClass, agentSessionID);
@@ -2135,6 +2839,13 @@ export class RealtimeClientSessionService {
      * configured timeout. If the tool is unrecognized, disallowed, or target resolution fails,
      * returns a structured "not available" result.
      *
+     * When this service holds the session's start-time projection, only the projected actions may
+     * run, whatever target the input names. When it holds none, the target agent's own metadata
+     * decides: another process prepared the session, the entry was evicted or lost on a restart, or
+     * the session was never started through this service (for example a row created through the
+     * entity API). That fallback skips the driver-capability gate but is still limited to the
+     * target's own direct-actions allowlist.
+     *
      * @param call The non-target tool call.
      * @param input The optional relayed tool input context.
      * @param contextUser The calling user context.
@@ -2156,11 +2867,9 @@ export class RealtimeClientSessionService {
                 Output: `Target agent is not available to execute '${call.ToolName}'.`
             };
         }
-        const candidateActions = this.getTargetAgentActions(target.ID);
-        const candidateWireMap = this.BuildWireActionMap(candidateActions);
-        const action = (input?.AgentSessionID ? this.sessionWireActionMaps.Get(input.AgentSessionID)?.get(call.ToolName) : undefined)
-            ?? candidateWireMap.get(call.ToolName)
-            ?? Array.from(candidateWireMap.entries()).find(([w]) => w.toLowerCase() === call.ToolName.trim().toLowerCase())?.[1];
+        const projection = input?.AgentSessionID ? this.sessionWireActionMaps.Get(input.AgentSessionID) : undefined;
+        const candidateWireMap = this.BuildWireActionMap(this.getTargetAgentActions(target.ID));
+        const action = this.findWireAction(projection, call.ToolName) ?? this.findWireAction(candidateWireMap, call.ToolName);
         if (!action) {
             return {
                 CallID: call.CallID,
@@ -2171,7 +2880,7 @@ export class RealtimeClientSessionService {
         const directConfig = input?.DirectActions
             ?? (input?.AgentSessionID ? this.sessionDirectConfigs.Get(input.AgentSessionID) : undefined)
             ?? GetDirectActionsConfig(this.resolveEffectiveConfig(target, undefined, target));
-        if (!IsActionAllowedForDirectInvocation(action.Name, directConfig)) {
+        if (!this.isInProjection(projection, action) || !IsActionAllowedForDirectInvocation(action.Name, directConfig)) {
             return {
                 CallID: call.CallID,
                 Success: false,
@@ -2232,6 +2941,24 @@ export class RealtimeClientSessionService {
             };
         }
     }
+    /**
+     * Finds the action a relayed tool name refers to: the exact wire name first, then a
+     * case-insensitive match.
+     */
+    findWireAction(wireMap, toolName) {
+        if (!wireMap) {
+            return undefined;
+        }
+        const wanted = toolName.trim().toLowerCase();
+        return wireMap.get(toolName) ?? Array.from(wireMap.entries()).find(([wireName]) => wireName.toLowerCase() === wanted)?.[1];
+    }
+    /**
+     * True when the action is in the session's start-time projection, or when this service holds no
+     * projection for the session (see {@link executeNonTargetTool} for when that happens).
+     */
+    isInProjection(projection, action) {
+        return !projection || Array.from(projection.values()).some(projected => UUIDsEqual(projected.ID, action.ID));
+    }
     /**
      * Parses JSON arguments string into a key-value record of parameters.
      * Distinguishes "no arguments" (valid for zero-param action) from "unparseable JSON".