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

package/dist/realtime/realtime-client-session-service.d.ts

@@ -32,11 +32,36 @@
 import { UserInfo, IMetadataProvider } from '@memberjunction/core';
 import { MJLruCache } from '@memberjunction/global';
 import { MJActionEntityExtended } from '@memberjunction/actions-base';
-import { BaseRealtimeModel, ChatMessage, ClientRealtimeSessionConfig, AIAPIKey, AIAPIKeyResolver, IRealtimeSession, JSONObject, RealtimeSessionParams, RealtimeToolCall, RealtimeToolDefinition } from '@memberjunction/ai';
-import { MJAIAgentEntityExtended, MJAIModelEntityExtended, MJAIAgentRunEntityExtended, AgentExecutionProgressCallback, ExecuteAgentResult, AppContextSnapshot } from '@memberjunction/ai-core-plus';
+import { BaseRealtimeModel, ChatMessage, ClientRealtimeSessionConfig, AIAPIKey, AIAPIKeyResolver, AICredentialScope, IRealtimeSession, JSONObject, RealtimeAvatarStatus, RealtimeSessionParams, RealtimeToolCall, RealtimeToolDefinition } from '@memberjunction/ai';
+import { MJAIAgentEntityExtended, MJAIModelEntityExtended, MJAIAgentRunEntityExtended, AgentExecutionProgressCallback, ExecuteAgentResult, AppContextSnapshot, type IAgentSettings, type RealtimeChannelCandidate, type RealtimeSessionClientPolicy, type RealtimeSessionClientTools } from '@memberjunction/ai-core-plus';
+import { type RealtimeAvatarResolution } from './realtime-avatar-resolution.js';
 import { RealtimeToolBroker, RealtimeColleague, DelegateToTargetRequest, DelegatedResult, DelegatedRunArtifact, ToolExecutionResult } from './realtime-tool-broker.js';
 import { RealtimeAllowedAgent, RealtimeCoAgentConfig, RealtimeDirectActionsConfig } from './realtime-coagent-config.js';
 import { RealtimeVendorSelection } from './realtime-vendor-resolution.js';
+import { type RealtimeUsageRecord } from '@memberjunction/ai-engine-base';
+import { type RealtimeChannelRegistryRow } from './realtime-channel-policy.js';
+/**
+ * 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 declare const BRIDGE_SESSION_CLOSE_WAIT_MS = 5000;
+/**
+ * Context passed to {@link PrepareClientSessionInput.ResolveHostTools} describing the
+ * model, vendor, and driver resolved for the realtime session.
+ */
+export interface RealtimeHostToolsResolutionContext {
+    /** The resolved model entity ID. */
+    ModelID?: string;
+    /** The resolved model vendor ID, if known. */
+    ModelVendorID?: string;
+    /** The resolved realtime driver class name (e.g. 'OpenAILiveRealtime'). */
+    DriverClass?: string;
+}
+/**
+ * Resolver callback signature for dynamically resolving host tools prior to session start.
+ */
+export type RealtimeHostToolsResolver = (resolved: RealtimeHostToolsResolutionContext) => RealtimeToolDefinition[] | undefined;
 /**
  * Input for {@link RealtimeClientSessionService.PrepareClientSession}.
  *
@@ -56,6 +81,13 @@ export interface PrepareClientSessionInput {
      * client-initiated session today.
      */
     APIKeys?: AIAPIKey[];
+    /**
+     * The run's credential scope (`ExecuteAgentParams.CredentialScope`). `'RuntimeOnly'` makes
+     * {@link PrepareClientSessionInput.APIKeys} the whole key chain: a vendor they do not key is not
+     * selected, and the {@link RealtimeClientSessionService.getAPIKeyForDriver} seam (by default the
+     * platform's environment key) is never consulted. Absent ⇒ `'Any'`.
+     */
+    CredentialScope?: AICredentialScope;
     /** The Realtime Co-Agent entity. Provide this OR {@link PrepareClientSessionInput.CoAgentID}. */
     CoAgent?: MJAIAgentEntityExtended;
     /** The Realtime Co-Agent id (resolved from cached metadata). Provide this OR {@link PrepareClientSessionInput.CoAgent}. */
@@ -73,6 +105,15 @@ export interface PrepareClientSessionInput {
      * app layer (the cascade rests on type/co-agent/target/override only).
      */
     ApplicationID?: string;
+    /**
+     * The interactive channels the BROWSER reports it could mount in this session (key, code defaults,
+     * native tools, host-declared?). When present the service scopes them — registry kill switch, agent
+     * and app configuration (`realtime.channels`) — narrows/completes {@link ExtraTools} to match, and
+     * returns the resolved {@link RealtimeClientSessionPrepResult.ClientPolicy} for the browser to
+     * activate. Absent ⇒ no scoping (a client that predates channel scoping, or a host that mints
+     * through its own proxy): {@link ExtraTools} is used exactly as declared.
+     */
+    ChannelCandidates?: RealtimeChannelCandidate[];
     /**
      * Optional app-context snapshot — where the user is, what they see, and the live capability
      * manifest — injected into the companion system prompt at mint (the session-start half of the
@@ -82,6 +123,23 @@ export interface PrepareClientSessionInput {
     AppContext?: AppContextSnapshot;
     /** Prior conversation history to seed the model's context. Optional. */
     ConversationMessages?: ChatMessage[];
+    /**
+     * Tools the HOST (not the co-agent runtime) declares AND executes — e.g. a phone call's `transfer_call`,
+     * `send_dtmf` and `end_call`. They are added to the session's tool set but, unlike {@link ExtraTools}, are
+     * NOT described as interactive-surface tools in the prompt. The host executes them through the runtime's
+     * local tool handler ({@link BridgeRealtimeRuntime.SetLocalToolHandler}).
+     */
+    HostTools?: RealtimeToolDefinition[];
+    /**
+     * Optional callback that allows the host to resolve host tools dynamically based on
+     * the model, vendor, and driver actually resolved for the session, before session opening.
+     */
+    ResolveHostTools?: RealtimeHostToolsResolver;
+    /**
+     * Host-authored instructions appended to the system prompt (e.g. "this is an audio-only phone call …",
+     * the caller's number and verification status). Empty/absent adds nothing.
+     */
+    HostFraming?: string;
     /**
      * Pre-formatted, role-tagged transcript lines (`User: …` / `Assistant: …`, newline-separated)
      * from the caller's PRIOR session leg(s) when this session RESUMES one (`lastSessionId`).
@@ -132,6 +190,34 @@ export interface PrepareClientSessionInput {
      * addressing GATE is the bridge's `RegexAddressedMatcher`. Ignored unless {@link DisableAutoResponse}.
      */
     SelfNames?: string[];
+    /**
+     * `'room'` for a server-side (bridged) session whose host publishes the agent's avatar into a meeting room: the
+     * avatar request resolved for the voiced agent carries it (`RealtimeAvatarSettings.Delivery`), so a driver may
+     * render it there. Absent: a server-side session asks for no video (the driver logs `bridged`), and its avatar
+     * status says `bridged` also when the prep asked the driver for none, or the driver reported nothing. Ignored on a
+     * {@link PhoneCall}.
+     */
+    AvatarDelivery?: 'room';
+    /**
+     * `true` for a server-side session (a bridged meeting or a phone call), which can show the agent's avatar only when its
+     * host publishes it into a room ({@link AvatarDelivery} `'room'`). Without that, the default model walk's video
+     * preference skips the session: no model would bring it an avatar. Absent: a browser (client-direct) session.
+     */
+    ServerSide?: boolean;
+    /**
+     * `true` when the session is a phone call: a carrier call (Twilio, Vonage, RingCentral), or a call that reaches a
+     * LiveKit room through SIP. The caller hears the agent and sees nothing, so the session asks the driver for no avatar,
+     * even in a room that could show one, and reports why (`phone`); the avatar persona's voice is kept, and the default
+     * model walk prefers no avatar model. Absent: not a phone call.
+     */
+    PhoneCall?: boolean;
+    /**
+     * `false` when the app showing a browser session shows no agent video: none of its channels shows it (the embeddable
+     * widgets and the mobile app today; the mint's `showsAgentVideo` argument). The session then asks the driver for no
+     * avatar and reports why (`host`), the avatar persona's voice is kept, and the default model walk prefers no avatar
+     * model. Absent or `true`: the app may show it, and the browser decides at connect (`host` or `browser` then).
+     */
+    ShowsAgentVideo?: boolean;
     /**
      * Optional server-authoritative hard ceiling on the session's wall-clock duration, in seconds.
      * Threaded into {@link RealtimeSessionParams.MaxSessionSeconds} so a driver can bound the
@@ -140,6 +226,11 @@ export interface PrepareClientSessionInput {
      * deployments (a public web-widget guest's `VoiceMaxSessionMinutes`); omitted otherwise.
      */
     MaxSessionSeconds?: number;
+    /**
+     * When `true`, no direct actions are projected for the session, so the model gets none and the
+     * session's relays run none. Set for callers that may not run actions directly.
+     */
+    ExcludeDirectActions?: boolean;
 }
 /**
  * Result of {@link RealtimeClientSessionService.PrepareClientSession}.
@@ -214,6 +305,12 @@ export interface RealtimeClientSessionPrepResult {
      * (client drivers apply provider voice settings client-side in the client-direct topology).
      */
     EffectiveConfig?: RealtimeCoAgentConfig;
+    /**
+     * The resolved channel scope and client-tool tiers for the browser to activate — present only when
+     * the input carried {@link PrepareClientSessionInput.ChannelCandidates}. The transport layer returns
+     * it in the mint result and persists the in-session channel keys on the session.
+     */
+    ClientPolicy?: RealtimeSessionClientPolicy;
     /**
      * The effective narration pace (`realtime.narration.paceMs`) — minimum gap in ms between
      * spoken progress updates. `undefined` when not configured (clients/runners use their
@@ -222,6 +319,12 @@ export interface RealtimeClientSessionPrepResult {
      * `RealtimeSessionRunnerDeps.NarrationPaceMs`.
      */
     NarrationPaceMs?: number;
+    /**
+     * The live avatar the session asked for and whether it shows: granted, or audio only and why
+     * ({@link ResolveRealtimeAvatarStatus}). Absent when the voiced agent asked for no avatar (its video setting is
+     * off). The transport layer returns it in the mint result, so the call can say why it shows no avatar.
+     */
+    AvatarStatus?: RealtimeAvatarStatus;
 }
 /**
  * The resolved co-agent system prompt text plus the id of the prompt it came from, returned by
@@ -242,9 +345,15 @@ export interface CoAgentSystemPromptResolution {
 export interface ExecuteRelayedToolInput {
     /** The shared session id grouping this voice session's runs. */
     AgentSessionID: string;
-    /** The id of the (co-agent) run that owns this session, used as the delegated run's parent. Optional. */
+    /**
+     * The id of the (co-agent) run that owns this session, used as the delegated run's parent. Optional.
+     * The caller passes it only when it is a run of this session.
+     */
     ParentRunID?: string;
-    /** The top-level (lead) target agent id for `invoke-target-agent` delegation. */
+    /**
+     * The top-level (lead) target agent id for `invoke-target-agent` delegation. The caller must have
+     * checked that the acting user may run this agent.
+     */
     TargetAgentID: string;
     /**
      * The session's effective allowed delegation targets (the union-accumulated set from the config
@@ -256,7 +365,8 @@ export interface ExecuteRelayedToolInput {
     /**
      * Optional direct actions configuration for this session, derived once during session prep
      * (cascade: co-agent + runtime overrides + target + app settings). When present, direct action
-     * enforcement checks this configuration instead of recomputing from target alone.
+     * enforcement checks this configuration instead of recomputing from target alone. Pass it only
+     * from server-side state, never from a client-writable source such as a session's `Config`.
      */
     DirectActions?: RealtimeDirectActionsConfig;
     /** The tool call the browser relayed from the provider. */
@@ -277,9 +387,20 @@ export interface ExecuteRelayedToolInput {
      * Optional id of a previously-paused delegated run (Status `AwaitingFeedback`) to RESUME instead
      * of starting a fresh run. When set, {@link delegateToTarget} passes it as `lastRunId` (with
      * `autoPopulateLastRunPayload`) to {@link AgentRunner.RunAgent}, so the user's answer continues
-     * the SAME interactive run (e.g. confirming a Query Builder task graph).
+     * the SAME interactive run (e.g. confirming a Query Builder task graph). The caller passes it only
+     * when it is a run of this session.
      */
     ResumeRunID?: string;
+    /**
+     * The browser's GraphQL session id. Lets the delegated run execute client tools the surface
+     * registered, because the client-tool request channel is keyed on this id.
+     */
+    BrowserSessionID?: string;
+    /**
+     * The app-context snapshot the browser sent at session start, so the delegated run's prompt sees
+     * surface context and tools. It does not follow later navigation in the browser.
+     */
+    AppContext?: AppContextSnapshot;
     /**
      * The id of the human this delegation is FOR, threaded into the delegated run's `userId`.
      *
@@ -335,23 +456,85 @@ export interface RealtimeSessionParamsPrep {
     EffectiveConfig?: RealtimeCoAgentConfig;
     /** The assembled session params (TARGET-identity prompt, stable tools incl. invoke-target, voice, memory). */
     SessionParams?: RealtimeSessionParams;
+    /** The resolved channel scope + client-tool tiers, when the input carried channel candidates. */
+    ClientPolicy?: RealtimeSessionClientPolicy;
+    /**
+     * The avatar the session asks for, or why there is none; empty when the voiced agent asked for none. The session
+     * params carry the request itself (`SessionParams.Avatar`); this keeps the reason for the call's avatar status.
+     */
+    AvatarResolution?: RealtimeAvatarResolution;
 }
 /**
  * The runtime handle returned by {@link RealtimeClientSessionService.WireBridgeRealtimeSession} — the
  * server long-lived (bridged) counterpart to what `PrepareClientSession` returns for the browser. The
  * bridge holds this for the life of the session: the observability run ids (for nesting + correlation)
- * and an **idempotent** {@link Finalize} the bridge MUST call on teardown so the co-agent run + prompt
- * run don't dangle in `Running`. Finalize also runs automatically when the session's `Close()` is invoked
- * or the connection drops — calling it again is a safe no-op.
+ * and an **idempotent** {@link Finalize} that keeps the co-agent run + prompt run from dangling in
+ * `Running`. It runs when the session's `Close()` is invoked, once the model session has closed, and when
+ * the connection drops; whichever comes first runs it, and a later call waits for that run.
  */
 export interface BridgeRealtimeRuntime {
     /** The `MJ: AI Agent Runs` row id created for this voice session (delegated runs nest under it). */
     CoAgentRunID?: string;
     /** The `MJ: AI Prompt Runs` row id for the session's system prompt. */
     PromptRunID?: string;
-    /** Finalizes the co-agent + prompt run. Idempotent; safe to call from multiple teardown paths. */
-    Finalize: (success: boolean) => Promise<void>;
+    /**
+     * Writes the session's last usage, then finalizes the co-agent + prompt run; usage reported afterwards is not
+     * stored. Closing the session runs it after the model session closed, so what the session reports while closing
+     * is kept; calling it before `Close()` would drop that report. Idempotent, so every teardown path may call it: it
+     * runs once, and every call returns the first call's promise and resolves only once the runs are finalized. The
+     * first call decides the outcome: its `success` and `errorMessage` stand.
+     *
+     * The session's `Close()` finalizes with `success` true, so a host whose bridge start failed calls
+     * `Finalize(false, error)` BEFORE it closes the session: the run, its prompt run and its step then read `Failed`
+     * with the start's error, and the close finalizes nothing more.
+     *
+     * @param success `true` → `Completed`, `false` → `Failed`.
+     * @param errorMessage Why the session failed, stamped on the failed run, prompt run and step. Ignored on success.
+     */
+    Finalize: (success: boolean, errorMessage?: string) => Promise<void>;
+    /**
+     * Aborts every delegated run currently in flight for this session (and drops pending narration). This is the
+     * EXPLICIT cancel — on a phone it backs the `cancel_pending_work` tool — and is deliberately NOT what a
+     * barge-in does (see {@link CancelPendingNarration}). Returns how many were aborted (0 when nothing was
+     * running; never throws).
+     */
+    CancelInFlightDelegations: () => number;
+    /**
+     * Drops any queued spoken progress update without touching the delegated work — what a barge-in does. The
+     * caller took the floor, so a pending "still working on it" is stale, but the jobs they asked for keep
+     * running. Never throws.
+     */
+    CancelPendingNarration: () => void;
+    /**
+     * Installs (or clears, with `undefined`) the host's local tool handler. A tool call whose name the handler
+     * {@link BridgeLocalToolHandler.Handles} is executed by the host instead of the shared delegation path.
+     */
+    SetLocalToolHandler: (handler: BridgeLocalToolHandler | undefined) => void;
+    /**
+     * Whether the agent watches LiveKit meetings (`realtime.video.watchMeetings` in its effective configuration, which
+     * includes the voiced agent's own). The room coordinator reads it, with whether the session takes video, to decide
+     * whether the bot reads the cameras and screens people allow.
+     */
+    WatchesMeetingVideo: boolean;
+}
+/**
+ * Executes tools the host declared through {@link PrepareClientSessionInput.HostTools}. Bound after the session
+ * is wired because the object that can act on them (a phone call's bridge) does not exist until the bridge
+ * engine has started.
+ */
+export interface BridgeLocalToolHandler {
+    /** Whether this handler owns `toolName`. */
+    Handles(toolName: string): boolean;
+    /** Runs one call; the returned string is the JSON handed back to the model. Never needs to catch — errors are reported to the model. */
+    Execute(call: RealtimeToolCall): Promise<string>;
 }
+/**
+ * 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 declare function GetBridgeRealtimeRuntime(session: IRealtimeSession): BridgeRealtimeRuntime | undefined;
 /**
  * Outcome of resolving the realtime model for a session: either a usable {@link RealtimeModelResolution}
  * or a specific, human-readable failure reason (used for explicit preferred-model failures, where the
@@ -505,6 +688,11 @@ export declare class RealtimeClientSessionService {
      * @returns The prep result (Success + ClientConfig/SessionParams, or Success: false + ErrorMessage).
      */
     PrepareClientSession(input: PrepareClientSessionInput, contextUser: UserInfo, provider: IMetadataProvider): Promise<RealtimeClientSessionPrepResult>;
+    /**
+     * 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.
+     */
+    private resolveMintedAvatarStatus;
     /**
      * 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
@@ -515,12 +703,22 @@ export declare 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, …).
@@ -530,6 +728,47 @@ export declare class RealtimeClientSessionService {
      * @returns A {@link BridgeRealtimeRuntime} the bridge holds for the session lifetime.
      */
     WireBridgeRealtimeSession(session: IRealtimeSession, input: PrepareClientSessionInput, prep: RealtimeSessionParamsPrep, contextUser: UserInfo, provider: IMetadataProvider): Promise<BridgeRealtimeRuntime>;
+    /**
+     * 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.
+     */
+    private reportBridgedAvatarStatus;
+    /**
+     * 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.
+     */
+    private wireBridgeUsage;
+    /**
+     * 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}).
+     */
+    private createBridgeFinalizer;
+    /** Tool calls → the host's local handler or the shared delegation entry point, then the result back to the model. */
+    private wireBridgeToolCalls;
+    /**
+     * 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.
+     */
+    private finalizeOnBridgeClose;
     /**
      * Degenerate {@link BridgeRealtimeRuntime} for the rare case wiring is attempted without a resolved
      * co-agent: answer every tool call with a clear "not available" error and a no-op finalize. Keeps the
@@ -557,6 +796,57 @@ export declare class RealtimeClientSessionService {
      * @returns The prep result: `Success` + co-agent/resolution/effective-config/session-params, or `Success: false`.
      */
     PrepareRealtimeSessionParams(input: PrepareClientSessionInput, contextUser: UserInfo, provider: IMetadataProvider): Promise<RealtimeSessionParamsPrep>;
+    /**
+     * 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.
+     */
+    protected scopeSessionInput(input: PrepareClientSessionInput, effectiveConfig: RealtimeCoAgentConfig, contextUser: UserInfo, provider: IMetadataProvider, modelHasZeroDataRetention?: boolean): Promise<{
+        Input: PrepareClientSessionInput;
+        ClientPolicy?: RealtimeSessionClientPolicy;
+    }>;
+    /**
+     * 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).
+     */
+    protected modelHasZeroDataRetention(modelID: string | undefined, modelVendorID: string | undefined): boolean;
+    /**
+     * 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.
+     */
+    private withAppToolTier;
+    /**
+     * 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.
+     */
+    protected readChannelRegistry(provider: IMetadataProvider): RealtimeChannelRegistryRow[];
+    /**
+     * 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.
+     */
+    protected resolveSessionClientToolTiers(applicationId: string | undefined, targetAgentId: string, contextUser: UserInfo): Promise<RealtimeSessionClientTools>;
     /**
      * Resolves the EFFECTIVE realtime configuration via the surface-agnostic precedence cascade:
      * agent-TYPE `DefaultConfiguration` (base) < **co-agent** `TypeConfiguration` < **target agent**
@@ -572,6 +862,16 @@ export declare class RealtimeClientSessionService {
      * @returns The normalized effective configuration (possibly empty, never `null`).
      */
     protected resolveEffectiveConfig(coAgent: MJAIAgentEntityExtended, overridesJson?: string, targetAgent?: MJAIAgentEntityExtended | null, appSettingsJson?: string | null): RealtimeCoAgentConfig;
+    /**
+     * 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.
+     */
+    private logDeprecatedVideoKeys;
     /**
      * Resolves the APP cascade layer JSON from `Application.AgentSettings`: the `Realtime` overrides
      * (persona/disclosure/model) plus `RelevantAgents` mapped to the union-accumulated allowed-agent
@@ -586,6 +886,14 @@ export declare class RealtimeClientSessionService {
      * @returns The canonical app-layer JSON string, or `null`.
      */
     protected resolveAppRealtimeOverrides(applicationId: string | undefined, contextUser: UserInfo, provider: IMetadataProvider): Promise<string | null>;
+    /**
+     * 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`.
+     */
+    protected loadAppAgentSettings(applicationId: string | undefined, contextUser: UserInfo): Promise<IAgentSettings | null>;
     /**
      * Reads the co-agent's TYPE-level `DefaultConfiguration` from {@link AIEngine}'s cached agent
      * types. **Overridable seam**; tolerant — an absent type or unloaded cache returns `null`.
@@ -621,6 +929,20 @@ export declare class RealtimeClientSessionService {
      * `CompleteMessage`) when the save fails.
      */
     private createCoAgentRun;
+    /**
+     * 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: string | null | undefined, provider: IMetadataProvider, contextUser: UserInfo): void;
     /**
      * 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
@@ -650,8 +972,22 @@ export declare 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.
+     */
+    FinalizeCoAgentRun(coAgentRunID: string | null, promptRunID: string | null, contextUser: UserInfo, provider: IMetadataProvider, success?: boolean, coAgentRunStepID?: string | null, errorMessage?: string): Promise<void>;
+    /**
+     * 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.
      */
-    FinalizeCoAgentRun(coAgentRunID: string | null, promptRunID: string | null, contextUser: UserInfo, provider: IMetadataProvider, success?: boolean, coAgentRunStepID?: string | null): Promise<void>;
+    private rollUpCoAgentRunUsage;
     /**
      * Finalizes the **co-agent observability run(s)** for an agent session that were left `Running` because
      * the session was reaped WITHOUT a live in-memory handle — a prior-boot orphan or a cross-host teardown,
@@ -680,15 +1016,22 @@ export declare class RealtimeClientSessionService {
      * run — which is the replacement path that migration's design notes prescribe.
      */
     private findCoAgentChildLogIds;
-    /** Loads + finalizes the co-agent `AIAgentRun` if still `Running`. Tolerant: logs, never throws. */
+    /**
+     * Loads + finalizes the co-agent `AIAgentRun` if still `Running`, with `failure` as its `ErrorMessage` when it fails.
+     * Tolerant: logs, never throws.
+     */
     private finalizeAgentRun;
     /**
      * 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.
      */
     private finalizeRunStep;
-    /** Loads + finalizes the co-agent `AIPromptRun` if still `Running`. Tolerant: logs, never throws. */
+    /**
+     * Loads + finalizes the co-agent `AIPromptRun` if still `Running`, with `failure` as its `ErrorMessage` when it fails.
+     * Tolerant: logs, never throws.
+     */
     private finalizePromptRun;
     /**
      * Appends (or replaces) one transcript turn onto the co-agent's long-lived `AIPromptRun.Messages`,
@@ -715,12 +1058,27 @@ export declare 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.
      */
-    AccumulatePromptRunUsage(promptRunID: string, inputDelta: number, outputDelta: number, contextUser: UserInfo, provider: IMetadataProvider): Promise<boolean>;
+    AccumulatePromptRunUsage(promptRunID: string, inputDelta: number, outputDelta: number, contextUser: UserInfo, provider: IMetadataProvider, details?: RealtimeUsageRecord): Promise<boolean>;
+    /**
+     * 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).
+     */
+    private mergeUsageDetails;
+    /** One log line for each output video quantity the merge capped. */
+    private logClampedVideo;
     /** Parses the prompt run's `Messages` JSON into a mutable chat-message array (tolerant: `[]` on empty/malformed). */
     private parsePromptRunMessages;
     /**
@@ -795,15 +1153,41 @@ export declare 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).
      */
     protected resolveModelForSession(input: PrepareClientSessionInput, coAgent: MJAIAgentEntityExtended, effectiveConfig?: RealtimeCoAgentConfig): Promise<RealtimeModelResolutionOutcome>;
+    /**
+     * 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.
+     */
+    private resolveDefaultRealtimeModel;
+    /**
+     * 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.
+     */
+    protected ResolveAvatarRealtimeModel(coAgent: MJAIAgentEntityExtended, resolve?: AIAPIKeyResolver, credentialScope?: AICredentialScope): RealtimeModelResolution | 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
@@ -823,9 +1207,11 @@ export declare 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.
      */
-    protected resolveConfiguredModelPreference(effectiveConfig?: RealtimeCoAgentConfig, resolve?: AIAPIKeyResolver): RealtimeModelResolution | null;
+    protected resolveConfiguredModelPreference(effectiveConfig?: RealtimeCoAgentConfig, resolve?: AIAPIKeyResolver, credentialScope?: AICredentialScope, showsAvatar?: boolean): RealtimeModelResolution | null;
     /**
      * Looks up a model by ID (UUID-insensitive) or, failing that, by case/whitespace-insensitive
      * Name in {@link AIEngine}'s cached models. **Overridable seam**; tolerant of an unloaded cache.
@@ -841,9 +1227,11 @@ export declare 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).
      */
-    protected resolvePreferredRealtimeModel(preferredModelID: string, resolve?: AIAPIKeyResolver): RealtimeModelResolutionOutcome;
+    protected resolvePreferredRealtimeModel(preferredModelID: string, resolve?: AIAPIKeyResolver, credentialScope?: AICredentialScope, showsAvatar?: boolean): RealtimeModelResolutionOutcome;
     /**
      * Looks up a model by id in {@link AIEngine}'s cached models. **Overridable seam** for tests.
      *
@@ -864,9 +1252,11 @@ export declare 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`.
      */
-    protected resolveRealtimeModel(coAgent: MJAIAgentEntityExtended, resolve?: AIAPIKeyResolver): Promise<RealtimeModelResolution | null>;
+    protected resolveRealtimeModel(coAgent: MJAIAgentEntityExtended, resolve?: AIAPIKeyResolver, credentialScope?: AICredentialScope, showsAvatar?: boolean): Promise<RealtimeModelResolution | null>;
     /**
      * Shared tail of model resolution: picks the vendor (with a usable API key) for an
      * already-chosen model entity and instantiates its realtime driver.
@@ -879,9 +1269,26 @@ export declare 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.
      */
-    protected resolveVendorAndInstantiate(model: MJAIModelEntityExtended, resolve?: AIAPIKeyResolver): RealtimeModelResolution | null;
+    protected resolveVendorAndInstantiate(model: MJAIModelEntityExtended, resolve?: AIAPIKeyResolver, credentialScope?: AICredentialScope, showsAvatar?: boolean): RealtimeModelResolution | null;
+    /**
+     * 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.
+     */
+    private buildKeyChain;
+    /** Instantiates a vendor's realtime driver with its key from the chain; `null` when the key or the driver is missing. */
+    private instantiateRealtimeVendor;
     /**
      * Resolves the API key for a vendor driver class. **Overridable seam** (wraps the module-level
      * {@link GetAIAPIKey}) so tests can simulate present/absent keys without environment setup.
@@ -904,7 +1311,9 @@ export declare class RealtimeClientSessionService {
     protected createModelInstance(driverClass: string, apiKey: string): BaseRealtimeModel | null;
     /**
      * 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.
      *
@@ -947,9 +1356,32 @@ export declare 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.
      */
-    protected buildSessionParams(input: PrepareClientSessionInput, coAgent: MJAIAgentEntityExtended, modelApiName: string, contextUser: UserInfo, provider: IMetadataProvider, effectiveConfig?: RealtimeCoAgentConfig, driverClass?: string, modelID?: string, modelVendorID?: string): Promise<RealtimeSessionParams>;
+    protected buildSessionParams(input: PrepareClientSessionInput, coAgent: MJAIAgentEntityExtended, modelApiName: string, contextUser: UserInfo, provider: IMetadataProvider, effectiveConfig?: RealtimeCoAgentConfig, driverClass?: string, modelID?: string, modelVendorID?: string, resolvedAvatar?: RealtimeAvatarResolution): Promise<RealtimeSessionParams>;
+    /**
+     * 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.
+     */
+    protected ResolveSessionAvatar(input: PrepareClientSessionInput, coAgent: MJAIAgentEntityExtended, effectiveConfig: RealtimeCoAgentConfig | undefined, modelID: string | undefined, modelVendorID: string | undefined): RealtimeAvatarResolution;
+    /**
+     * 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.
+     */
+    private withAvatarVoice;
     /**
      * 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
@@ -1124,6 +1556,8 @@ export declare class RealtimeClientSessionService {
      * @returns The tools to register at session start.
      */
     protected buildStableToolSet(extraTools?: RealtimeToolDefinition[]): RealtimeToolDefinition[];
+    /** Appends the host-declared tools to a stable tool set, dropping any whose name is already taken. */
+    protected appendHostTools(tools: RealtimeToolDefinition[], hostTools?: RealtimeToolDefinition[]): RealtimeToolDefinition[];
     /**
      * 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.
@@ -1214,11 +1648,13 @@ export declare 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.
@@ -1269,17 +1705,27 @@ export declare class RealtimeClientSessionService {
      * @returns The active action entities assigned to the agent.
      */
     protected getTargetAgentActions(targetAgentID: string): MJActionEntityExtended[];
+    /**
+     * 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.
+     */
+    private projectDirectActions;
     /**
      * 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.
      * @returns The array of projected direct action tools (empty if unsupported or disabled).
      */
     BuildDirectActionTools(targetAgentID: string | undefined, effectiveConfig?: RealtimeCoAgentConfig, driverClass?: string, agentSessionID?: string): RealtimeToolDefinition[];
+    /** Records that a session projected no direct actions, so its relays run none. */
+    private recordEmptyProjection;
     /** @deprecated Use {@link BuildDirectActionTools}. */
     buildDirectActionTools(targetAgentID: string | undefined, effectiveConfig?: RealtimeCoAgentConfig, driverClass?: string, agentSessionID?: string): RealtimeToolDefinition[];
     /**
@@ -1296,12 +1742,29 @@ export declare 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.
      * @returns A {@link ToolExecutionResult} for the model's tool_response.
      */
     protected executeNonTargetTool(call: RealtimeToolCall, input?: ExecuteRelayedToolInput, contextUser?: UserInfo): Promise<ToolExecutionResult>;
+    /**
+     * Finds the action a relayed tool name refers to: the exact wire name first, then a
+     * case-insensitive match.
+     */
+    private findWireAction;
+    /**
+     * 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).
+     */
+    private isInProjection;
     /**
      * Parses JSON arguments string into a key-value record of parameters.
      * Distinguishes "no arguments" (valid for zero-param action) from "unparseable JSON".