Class RealtimeClientSessionService

Assembles the same memory/context block a loop agent injects, reusing AgentMemoryContextBuilder so there is no duplicated retrieval logic. The builder unshifts a system message onto a throwaway array, which we pull back out as plain text.

Builds the session-start app-context section from the AppContextSnapshot: where the user is, what they see, and the live capability manifest, rendered via the shared FormatAppContextNote (one wording for mint-time and streaming notes) under a clear heading. Returns '' when no snapshot was supplied or nothing salient survives.

Maps the effective config's union-accumulated allowedAgents into RealtimeColleague entries for the framing — resolving each target's display name + description from the agent cache and its effective per-target disclosure (GetDisclosureForTarget). The LEAD (the voiced target) is excluded so the co-agent never lists itself as a colleague. Empty when none configured.

Assembles the companion system prompt: the framing ("you are the voice for the target"), the co-agent's own system prompt text, the TARGET agent's identity/capabilities (Name + Description), the conversation history, and the same memory/context a loop agent assembles.

When the effective configuration carries a voice persona (realtime.voice.default), a short "Voice & manner" section (tone / speaking style) is appended after the co-agent's own prompt so the model speaks in the configured manner.

Builds the "interactive-surface tools" exception clause appended to the co-agent framing when the client supplied channel tools (browser_, Whiteboard_, …) as ExtraTools. Without it the co-agent — told to route ALL work through invoke-target-agent — delegates browser/whiteboard requests to the target agent (which has no live channel of its own) instead of driving the surface itself, then hallucinates a "missing session id". The tools ARE already in its set (buildStableToolSet merges [invokeTarget, ...extraTools]); this clause tells the model to USE them directly. Returns empty for pure-voice sessions (no ExtraTools), keeping that framing untouched. Generic by design — it names browser_ and Whiteboard_ tools only as examples, so any future client channel is covered automatically.

Builds the meeting-mode discipline clause — present only for a multi-agent meeting session (PrepareClientSessionInput.DisableAutoResponse). It tells the agent to hear the whole conversation but speak only when addressed (named) or clearly called on, and never to talk over others. This is the prompt half of "hear always, speak selectively"; the enforcement half is the model's disabled auto-response + the bridge's addressing gate. Empty for a 1:1 call (prompt unchanged). See plans/realtime/multi-agent-meeting-turn-taking.md.

Builds the provider-pact Config bag for the session: the effective config's matching per-provider voice settings (realtime.voice.providers.<provider>) merged UNDER any caller-supplied PrepareClientSessionInput.Config (the runtime bag wins per key). The settings objects are OPAQUE driver pacts — each server driver consumes its own keys exactly as it consumes any other entry of the open config bag (OpenAI spreads it into session.update, AssemblyAI reads voice, Gemini merges it last). Returns the original input.Config (possibly undefined) when no provider settings match, preserving the pre-config behavior byte-for-byte.

Builds the RealtimeSessionParams for the client-direct session: the companion system prompt plus the stable, target-independent tool set.

Builds the stable, target-independent tool set every voice session exposes: the single invoke-target-agent tool plus any caller-supplied extra tools. The target is a runtime argument inside the call, never a per-target tool — this keeps the provider contract identical across targets.

Builds the RealtimeToolBroker for a relayed tool call, wiring DelegateToTarget to a target-agent run and ExecuteTool to a structured "not available" placeholder.

Ensures AIEngine metadata is loaded before resolution. Overridable seam so tests can skip the DB-backed config load.

Creates the server-side co-agent observability runs for a voice session: an AIAgentRun (Status Running), and — when a co-agent system prompt resolved — a linked AIPromptRun (Status Running, AgentRunID = the co-agent run, AgentID = the co-agent) plus a single MJ: AI Agent Run Steps row (StepType Prompt) so the co-agent run's Timeline is non-empty. Delegated target-agent runs nest under the returned CoAgentRunID via ParentRunID.

Best-effort: returns null (and logs) when the co-agent run cannot be saved, so callers can continue without observability rather than failing the whole prepare. A failed prompt-run or run-step save just omits that id.

Creates artifact(s) from a completed delegated run's payload — the voice-path equivalent of the chat path's artifact step in AgentRunner.RunAgentInConversation. Delegated voice runs execute via AgentRunner.RunAgent directly (no conversation detail), so without this step they would never produce artifacts at all.

Eligibility guards (all must hold, mirroring the chat path's processArtifacts):

• the run succeeded and did NOT pause awaiting feedback (a paused run has no deliverable yet);
• the run returned a non-empty payload.

The DB work is delegated to processRunArtifacts (an overridable seam), which reuses AgentRunner.ProcessAgentArtifacts — so ArtifactCreationMode, DefaultArtifactTypeID, name extraction, and duplicate-version dedup all behave exactly as in chat. Best-effort: any failure is logged and returns undefined; artifact surfacing never fails the delegation.

Instantiates the realtime driver for a vendor driver class via the ClassFactory. Overridable seam so tests can return a mock driver.

Delegates an invoke-target-agent call to the target agent via AgentRunner.RunAgent.

Threads the broker-owned abort signal (combined with any caller signal) into the child run's cancellationToken, links the child run to the co-agent run via parentRunID, and propagates agentSessionID so both runs group under the same session. Mirrors BaseAgent.delegateRealtimeToTarget.

Comma-joined display names of the session's allowed colleagues (labels preferred), for error guidance.

Routes a non-target tool call. For now this returns a structured "not available" result — the richer client/UI/action routing is wired in a later phase. Documented minimal seam.

Looks up a model by id in AIEngine's cached models. Overridable seam for tests.

Looks up a model by ID (UUID-insensitive) or, failing that, by case/whitespace-insensitive Name in AIEngine's cached models. Overridable seam; tolerant of an unloaded cache.

Reads the co-agent's TYPE-level DefaultConfiguration from AIEngine's cached agent types. Overridable seam; tolerant — an absent type or unloaded cache returns null.

Resolves the API key for a vendor driver class. Overridable seam (wraps the module-level GetAIAPIKey) so tests can simulate present/absent keys without environment setup.

Reads the co-agent's own system prompt text from its highest-priority active agent prompt, mirroring BaseAgent.loadAgentConfiguration's child-prompt resolution.

Loads the co-agent run entity behind ExecuteRelayedToolInput.ParentRunID so the delegated run can link to it via parentRun (→ ParentRunID). Returns null when no id was supplied or the run cannot be loaded (delegation proceeds without parent linkage rather than failing the whole call).

The DB-backed artifact-creation seam: runs AgentRunner.ProcessAgentArtifacts WITHOUT a conversation detail (the voice path has none — the artifact + version are created and the junction link is skipped), then loads the artifact header for its display name.

Artifacts whose Visibility resolved to System Only (the agent's ArtifactCreationMode) are created but NOT surfaced to the overlay — matching how chat hides them from users.

Overridable seam so tests can exercise createDelegatedRunArtifacts' eligibility guards without a DB.

Resolves the APP cascade layer JSON from Application.AgentSettings: the Realtime overrides (persona/disclosure/model) plus RelevantAgents mapped to the union-accumulated allowed-agent set, all translated into the canonical {"realtime":{…}} shape via BuildAppRealtimeOverridesJson.

One tiny by-ID read (served from the provider's RunView cache on repeat). Tolerant — any failure, a missing app, or an app with no AgentSettings returns null (no app layer), never throws.

Resolves the co-agent from either the supplied entity or its id (from cached metadata).

Resolves the co-agent's highest-priority active system prompt, returning both its template text and its prompt id. The id is surfaced so PrepareClientSession can create a linked co-agent AIPromptRun for observability. Mirrors BaseAgent.loadAgentConfiguration's child-prompt resolution.

Resolves the effective config's realtime.modelPreference (an MJ: AI Models Name OR ID) into a usable realtime model. TOLERANT by design — this is a METADATA preference, so any failure (unknown model, inactive, wrong type, no vendor/key) logs a warning and returns null, falling through to the default highest-PowerRank resolution. Contrast with the explicit runtime choice (resolvePreferredRealtimeModel), which fails loud.

Resolves the primary-scope pair a returning visitor's memory is filed under, mirroring the recap side (writeReturningVisitorRecap's resolveRecapScope):

• linked visitor → (Conversation.LinkedEntityID, Conversation.LinkedRecordID)
• linked anonymous → (the "MJ: Conversations" entity, Conversation.LastConversationID)
• brand-new visitor → undefined (no scoped memory)

Best-effort: any failure (no conversation id, load failure, entity not found) resolves to undefined so memory injection silently falls back to unscoped behavior.

Resolves which agent a delegation should run, given an optional colleague name the model passed.

• No name → the lead ExecuteRelayedToolInput.TargetAgentID (classic single-target).
• A name matching an allowed colleague (by label, resolved agent Name, or id — case/whitespace insensitive) OR the lead's own name → that agent.
• A name matching nothing in the union/lead → an error result naming the available colleagues, so the model self-corrects conversationally rather than silently delegating to the wrong agent.

The allowed union is an affordance/UX filter; CanRun on the resolved agent (inside the agent run) remains the security boundary — both apply.

Resolves the EFFECTIVE realtime configuration via the surface-agnostic precedence cascade: agent-TYPE DefaultConfiguration (base) < co-agent TypeConfiguration < target agent TypeConfiguration < (pre-authorized) runtime override — deep-merged per key and normalized. The target layer is what makes a voiced agent (Sage, Marketing Agent, …) carry its own voice/model regardless of host. Tolerant end-to-end: malformed layers contribute nothing and an unloaded metadata cache yields no type defaults. See plans/realtime/realtime-core-host-convergence.md.

Resolves the realtime model for a session, honoring an explicit user choice when present.

• With PrepareClientSessionInput.PreferredModelID: resolve THAT model strictly via resolvePreferredRealtimeModel — failures return a specific reason and never fall back to another model (the user explicitly chose). (The transport layer has already authorization-gated a deviating explicit choice.)
• Else, with an effective-config realtime.modelPreference (name or id): resolve it via 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 resolveRealtimeModel (highest-PowerRank active Realtime model), with the generic noModelMessage on failure.

Resolves the DB-driven progress-narration instruction template: the Active MJ: AI Prompts row named RealtimeClientSessionService.NarrationPromptName, read from AIEngine's cached prompts. When the current name is absent, falls back to the DEPRECATED RealtimeClientSessionService.LegacyNarrationPromptName (pre-rename seed) with a deprecation log. Tolerant: returns null (never throws) when neither prompt is present, the text is empty, or the engine cache is unavailable — clients fall back to their built-in narration instruction text.

Strictly resolves an EXPLICITLY requested realtime model. Each precondition failure returns a clear, user-facing reason naming the model — there is NO fallback to another model, because the caller's user explicitly chose this one.

Resolves the Realtime model + vendor driver + API key, mirroring BaseAgent's server-bridged resolution: highest-power active model of AIModelType Realtime; highest-priority active vendor whose DriverClass has a resolvable API key; instantiated via the ClassFactory.

Overridable seam. Test subclasses override this to return a mock model so the service can be exercised without provider SDKs or DB metadata. Returns null (never throws) when any step can't be satisfied.

Resolves the target agent entity from cached metadata.

Shared tail of model resolution: picks the vendor (with a usable API key) for an already-chosen model entity and instantiates its realtime driver.

Selects the highest-priority active vendor for a model whose DriverClass has a resolvable API key. Mirrors BaseAgent.selectRealtimeVendor.