@memberjunction/ai-agents 5.40.2 → 5.42.0

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

@@ -0,0 +1,1026 @@
+/**
+ * @fileoverview Server-agnostic preparer + tool relay for a CLIENT-DIRECT realtime session
+ * (the Realtime Co-Agent dual-topology design).
+ *
+ * In the client-direct topology the browser opens its OWN provider socket (e.g. WebRTC) using a
+ * server-minted ephemeral token, but the **server** still owns the system prompt and tool set and
+ * **executes** every tool call the browser relays back. This service is the server-side half of
+ * that contract. It does two things:
+ *
+ * 1. {@link RealtimeClientSessionService.PrepareClientSession} — resolves the Realtime model,
+ *    assembles the companion system prompt (co-agent prompt + target identity + history + memory),
+ *    builds the stable, target-independent tool set (always including `invoke-target-agent`), and
+ *    asks the model to mint a {@link ClientRealtimeSessionConfig} (ephemeral token + provider
+ *    session config) the browser applies verbatim.
+ * 2. {@link RealtimeClientSessionService.ExecuteRelayedTool} — executes a single tool call the
+ *    browser relayed, routing it through the shared {@link RealtimeToolBroker} so the result is
+ *    byte-for-byte identical to the server-bridged path. `invoke-target-agent` delegates to the
+ *    target agent via {@link AgentRunner.RunAgent}; every other tool returns a structured
+ *    "not available" result for now (action wiring is a later phase).
+ *
+ * **Why this duplicates BaseAgent.** The private helpers in `BaseAgent.executeRealtimeSession`
+ * (model resolution, companion-prompt assembly, target-agent resolution, delegation) are the
+ * server-bridged equivalents of the logic here, but they are `private` to `BaseAgent` and bound to
+ * an in-flight `AIAgentRun`/`StartSession` lifecycle. This service mirrors that logic for the
+ * client-direct topology, which has no server-side session loop. **A future refactor should extract
+ * a shared `RealtimeSessionPreparer`** that both `BaseAgent` and this service consume, eliminating
+ * the duplication. Until then, keep the two in sync intentionally.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { UserInfo, IMetadataProvider } from '@memberjunction/core';
+import { BaseRealtimeModel, ChatMessage, ClientRealtimeSessionConfig, IRealtimeSession, JSONObject, RealtimeSessionParams, RealtimeToolCall, RealtimeToolDefinition } from '@memberjunction/ai';
+import { MJAIAgentEntityExtended, MJAIModelEntityExtended, MJAIAgentRunEntityExtended, AgentExecutionProgressCallback, ExecuteAgentResult } from '@memberjunction/ai-core-plus';
+import { RealtimeToolBroker, DelegateToTargetRequest, DelegatedResult, DelegatedRunArtifact, ToolExecutionResult } from './realtime-tool-broker.js';
+import { RealtimeCoAgentConfig } from './realtime-coagent-config.js';
+/**
+ * Input for {@link RealtimeClientSessionService.PrepareClientSession}.
+ *
+ * The co-agent may be supplied either as a fully-loaded entity (`CoAgent`) or by id (`CoAgentID`),
+ * which is resolved from {@link AIEngine}'s cached agents. The target agent is always supplied by
+ * id — it is a runtime choice made when the voice session starts.
+ */
+export interface PrepareClientSessionInput {
+    /** 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}. */
+    CoAgentID?: string;
+    /** The top-level target agent the co-agent voices on behalf of (a runtime parameter). */
+    TargetAgentID: string;
+    /** The shared session id grouping this voice session's runs. */
+    AgentSessionID: string;
+    /** Optional conversation id the session is attached to — stamped on the co-agent observability run. */
+    ConversationID?: string;
+    /** Prior conversation history to seed the model's context. Optional. */
+    ConversationMessages?: ChatMessage[];
+    /**
+     * Pre-formatted, role-tagged transcript lines (`User: …` / `Assistant: …`, newline-separated)
+     * from the caller's PRIOR session leg(s) when this session RESUMES one (`lastSessionId`).
+     * The transport layer (the MJServer resolver) loads, ownership-checks, and caps this
+     * (~30 turns / ~8k chars, oldest dropped) before threading it here; the service only
+     * FRAMES it into the system prompt as a clearly-labeled prior-conversation section so the
+     * model remembers the previous leg. Optional — absent for fresh sessions, and any
+     * upstream load failure simply omits it (hydration never blocks a start).
+     */
+    PriorTranscript?: string;
+    /** Optional user-scope id for memory/context retrieval (falls back to the context user). */
+    UserID?: string;
+    /** Optional company-scope id for memory/context retrieval. */
+    CompanyID?: string;
+    /** Optional provider-specific session config bag (voice, language, turn detection, etc.). */
+    Config?: JSONObject;
+    /** Optional extra, target-independent tools to expose in addition to `invoke-target-agent`. */
+    ExtraTools?: RealtimeToolDefinition[];
+    /**
+     * Optional EXPLICIT realtime model choice (`MJ: AI Models.ID`). When set, that exact model is
+     * used — it must be Active, of AIModelType `Realtime`, and have an active vendor whose
+     * `DriverClass` resolves an API key. If the preferred model cannot be satisfied the prepare
+     * FAILS with a clear reason (no silent fallback — the user explicitly chose). When omitted,
+     * the default highest-PowerRank resolution applies.
+     */
+    PreferredModelID?: string;
+    /**
+     * Optional RUNTIME configuration-override layer (the most-specific layer of the effective
+     * configuration merge: type `DefaultConfiguration` ← agent `TypeConfiguration` ← this).
+     * **Pre-authorized by the transport layer** — the MJServer resolver gates it behind the
+     * `Realtime: Advanced Session Controls` authorization BEFORE threading it here; the service
+     * trusts the input. Malformed JSON is tolerated (it simply contributes nothing to the merge).
+     */
+    ConfigOverridesJson?: string;
+    /**
+     * **Multi-agent meeting mode.** When `true`, the agent joins as one of several voices in a shared
+     * room: its model's **blind auto-response is disabled** (the session Config carries
+     * `disableAutoResponse`, which providers translate to e.g. OpenAI `turn_detection.create_response=false`)
+     * and a meeting-aware clause is added to the prompt so it **hears everything but speaks only when
+     * addressed**. The bridge becomes the sole speech trigger (gated by its turn policy). Absent/`false`
+     * = a 1:1 call with the model's normal auto-response. See
+     * `plans/realtime/multi-agent-meeting-turn-taking.md`.
+     */
+    DisableAutoResponse?: boolean;
+    /**
+     * The names the meeting-aware prompt tells the agent it answers to (its own display name + aliases).
+     * Used ONLY to phrase the "you are addressed when someone says one of these" guidance; the actual
+     * addressing GATE is the bridge's `RegexAddressedMatcher`. Ignored unless {@link DisableAutoResponse}.
+     */
+    SelfNames?: string[];
+}
+/**
+ * Result of {@link RealtimeClientSessionService.PrepareClientSession}.
+ *
+ * On success, {@link RealtimeClientSessionPrepResult.ClientConfig} is the server-minted config the
+ * browser applies, and {@link RealtimeClientSessionPrepResult.SessionParams} is the params the
+ * server used to mint it (handy for the resolver to echo/persist). On failure, `Success` is `false`
+ * and `ErrorMessage` explains why — this method never throws for an unresolvable model/key.
+ */
+export interface RealtimeClientSessionPrepResult {
+    /** Whether the client session config was minted successfully. */
+    Success: boolean;
+    /** The minted client-direct session config (token + provider session config). Present on success. */
+    ClientConfig?: ClientRealtimeSessionConfig;
+    /** The session params the server built (system prompt, model, tools). Present on success. */
+    SessionParams?: RealtimeSessionParams;
+    /**
+     * ID of the server-side co-agent observability `AIAgentRun` created for this session. Present
+     * when the run was created successfully; absent when run creation was skipped or failed
+     * (observability is best-effort and never fails the prepare). Delegated target-agent runs nest
+     * under this run via `ParentRunID`, and {@link RealtimeClientSessionService.FinalizeCoAgentRun}
+     * closes it when the session ends.
+     */
+    CoAgentRunID?: string;
+    /**
+     * ID of the server-side co-agent `AIPromptRun` linked to {@link RealtimeClientSessionPrepResult.CoAgentRunID}.
+     * Present only when the co-agent's system prompt resolved (so a prompt run could be created).
+     */
+    PromptRunID?: string;
+    /**
+     * ID of the single `MJ: AI Agent Run Steps` row created under {@link RealtimeClientSessionPrepResult.CoAgentRunID}
+     * for the realtime session's system prompt (StepType `Prompt`, TargetID = the system prompt,
+     * TargetLogID = {@link RealtimeClientSessionPrepResult.PromptRunID}). It makes the co-agent run's
+     * Timeline non-empty. Present only when the co-agent's system prompt resolved AND the step saved
+     * (step creation is best-effort, like the runs themselves). Finalized alongside the runs by
+     * {@link RealtimeClientSessionService.FinalizeCoAgentRun}.
+     */
+    CoAgentRunStepID?: string;
+    /** A human-readable failure reason. Present on failure. */
+    ErrorMessage?: string;
+    /** The `MJ: AI Models` row id of the realtime model the session was minted with. Present on success. */
+    ModelID?: string;
+    /** The display name of the realtime model the session was minted with. Present on success. */
+    ModelName?: string;
+    /**
+     * The DB-driven progress-narration instruction template (the `Realtime Co-Agent - Progress
+     * Narration` prompt's `TemplateText`, containing a `{{ progressMessage }}` placeholder).
+     * `undefined` when that prompt is not present in metadata — clients fall back to their
+     * built-in narration instruction text.
+     */
+    NarrationInstructionsTemplate?: string;
+    /**
+     * The RESOLVED effective realtime configuration for this session (type defaults ← agent
+     * config ← runtime overrides, deep-merged + normalized). Present on success — `{}` when no
+     * layer configured anything. Surfaced so the transport layer can echo it to the client
+     * (client drivers apply provider voice settings client-side in the client-direct topology).
+     */
+    EffectiveConfig?: RealtimeCoAgentConfig;
+    /**
+     * The effective narration pace (`realtime.narration.paceMs`) — minimum gap in ms between
+     * spoken progress updates. `undefined` when not configured (clients/runners use their
+     * built-in default). In the CLIENT-DIRECT topology narration pacing is enforced client-side,
+     * so this is surfaced for the browser; the server-bridged runner consumes it directly via
+     * `RealtimeSessionRunnerDeps.NarrationPaceMs`.
+     */
+    NarrationPaceMs?: number;
+}
+/**
+ * The resolved co-agent system prompt text plus the id of the prompt it came from, returned by
+ * {@link RealtimeClientSessionService.resolveCoAgentSystemPrompt}.
+ */
+export interface CoAgentSystemPromptResolution {
+    /** The co-agent's system prompt template text (empty string when none is configured). */
+    Text: string;
+    /** The `MJ: AI Prompts` row id, or `null` when the co-agent has no active prompt. */
+    PromptID: string | null;
+}
+/**
+ * Input for {@link RealtimeClientSessionService.ExecuteRelayedTool}.
+ *
+ * Carries the single tool call the browser relayed plus the linkage needed to run a delegated
+ * target-agent run under the same session.
+ */
+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. */
+    ParentRunID?: string;
+    /** The top-level target agent id for `invoke-target-agent` delegation. */
+    TargetAgentID: string;
+    /** The tool call the browser relayed from the provider. */
+    Call: RealtimeToolCall;
+    /**
+     * Optional abort signal so a barge-in on the browser can cancel an in-flight delegated run.
+     * Threaded into the delegated agent run's `cancellationToken`.
+     */
+    AbortSignal?: AbortSignal;
+    /**
+     * Optional progress callback invoked with each delegated-run progress event (mirrors the normal
+     * agent-run path's `onProgress`). The transport layer (the MJServer resolver) publishes these so
+     * the realtime model can narrate the target agent's progress while it runs. When omitted, the
+     * delegated run streams nothing and the model only receives the final tool result.
+     */
+    OnProgress?: AgentExecutionProgressCallback;
+    /**
+     * 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).
+     */
+    ResumeRunID?: string;
+}
+/**
+ * The resolved Realtime model plus its identifiers, returned by the model-resolution seam.
+ */
+export interface RealtimeModelResolution {
+    /** The instantiated realtime driver. */
+    Model: BaseRealtimeModel;
+    /** The `MJ: AI Models` row id. */
+    ModelID: string;
+    /** The chosen vendor id. */
+    VendorID: string;
+    /** The vendor API name passed to the provider as the model id. */
+    APIName: string;
+    /** The model's display name (`MJ: AI Models.Name`). Optional for back-compat with test seams. */
+    ModelName?: string;
+    /**
+     * The chosen vendor's `DriverClass` (e.g. `OpenAIRealtime`). Used to match the effective
+     * config's per-provider voice settings (`realtime.voice.providers`) onto the driver's open
+     * `Config` bag. Optional for back-compat with test seams.
+     */
+    DriverClass?: string;
+}
+/**
+ * Output of {@link RealtimeClientSessionService.PrepareRealtimeSessionParams} — the host-agnostic prep that
+ * every realtime surface consumes before opening a session its own way. Carries the assembled
+ * {@link RealtimeSessionParams} plus the resolved co-agent / model / effective config the openers need.
+ */
+export interface RealtimeSessionParamsPrep {
+    /** Whether prep succeeded. When false, only {@link ErrorMessage} is set. */
+    Success: boolean;
+    /** Failure reason (present only when {@link Success} is false). */
+    ErrorMessage?: string;
+    /** The resolved co-agent (the Realtime-type agent that does the voicing). */
+    CoAgent?: MJAIAgentEntityExtended;
+    /** The resolved realtime model + identifiers. */
+    Resolution?: RealtimeModelResolution;
+    /** The effective config from the full precedence cascade (type-default < co-agent < target < override). */
+    EffectiveConfig?: RealtimeCoAgentConfig;
+    /** The assembled session params (TARGET-identity prompt, stable tools incl. invoke-target, voice, memory). */
+    SessionParams?: RealtimeSessionParams;
+}
+/**
+ * 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.
+ */
+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>;
+}
+/**
+ * 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
+ * generic "no model" message would hide WHY the user's chosen model couldn't be used).
+ */
+export interface RealtimeModelResolutionOutcome {
+    /** The resolved model. Present on success. */
+    Resolution?: RealtimeModelResolution;
+    /** Why resolution failed. Present on failure. */
+    ErrorMessage?: string;
+}
+/**
+ * Server-agnostic service that prepares a client-direct realtime session and executes the tool
+ * calls the browser relays back. Constructed per-request (a normal injectable service — NOT a
+ * singleton) so the {@link UserInfo} and {@link IMetadataProvider} are always request-scoped.
+ *
+ * Every public method takes the `contextUser` and `provider` explicitly — this service never
+ * reaches for the global default provider, so it is safe in multi-provider/multi-tenant servers.
+ */
+export declare class RealtimeClientSessionService {
+    /**
+     * The seeded name of the `MJ: AI Prompts` row whose `TemplateText` carries the first-person
+     * progress-narration instructions (with a `{{ progressMessage }}` placeholder). Resolved at
+     * session prepare time so the browser narrates with DB-driven, product-tunable wording.
+     * Canonical value lives in `realtime-narration.ts` (shared with the server-bridged runner path).
+     */
+    static readonly NarrationPromptName = "Realtime Co-Agent - Progress Narration";
+    /**
+     * DEPRECATED legacy name of the narration prompt, from before the co-agent's rename from
+     * "Voice Co-Agent" to "Realtime Co-Agent". Deployments that have not re-synced the prompt seed
+     * still carry this name, so {@link resolveNarrationInstructionsTemplate} falls back to it
+     * (with a deprecation log) when {@link RealtimeClientSessionService.NarrationPromptName} is absent.
+     */
+    static readonly LegacyNarrationPromptName = "Voice Co-Agent - Progress Narration";
+    /**
+     * IN-FLIGHT DELEGATION REGISTRY — the server half of the client-direct CANCEL channel.
+     *
+     * Every relayed tool call registers an {@link AbortController} under
+     * `(agentSessionID, callID)` for the duration of {@link ExecuteRelayedTool}; the
+     * `CancelRealtimeSessionTool` mutation aborts entries via
+     * {@link CancelInFlightDelegations} so an explicit user cancel (the overlay's per-card ✕)
+     * kills the delegated target-agent run mid-flight. Entries are removed on completion
+     * (success, failure, or abort), so the registry only ever holds truly in-flight calls.
+     *
+     * Keys are normalized (trimmed, lowercased) so SQL Server's uppercase UUIDs and
+     * PostgreSQL's lowercase UUIDs address the same entry.
+     *
+     * NOTE: this registry is per-service-instance state (the resolver holds ONE shared service
+     * per server process), not per-request state — it deliberately spans requests so the cancel
+     * mutation can reach the execute mutation's in-flight controller.
+     */
+    private readonly inFlightDelegations;
+    /**
+     * Per-`AIPromptRun` write serialization. Both the high-frequency usage checkpoint
+     * ({@link AccumulatePromptRunUsage}) and the per-turn message append ({@link AppendPromptRunMessage})
+     * do load-modify-save on the SAME run row. Run concurrently, the frequent usage save would rewrite the
+     * whole row — including the STALE `Messages` it loaded — and perpetually clobber freshly-appended turns
+     * back to an empty snapshot (the "transcript never persists" bug). Funnelling every write for a given
+     * run through a single promise chain makes each load happen AFTER the prior save committed, so no writer
+     * overwrites another's field. Keyed by promptRunID; the entry is dropped on {@link finalizePromptRun}.
+     */
+    private readonly promptRunWriteChains;
+    /**
+     * Serializes `task` against all other writes to the same `AIPromptRun` (see {@link promptRunWriteChains}).
+     * Tasks run in call order; a failing task never breaks the chain for the next one. Returns the task's result.
+     */
+    private serializePromptRunWrite;
+    /**
+     * Prepares a client-direct realtime session: resolves the model, assembles the companion
+     * system prompt + stable tool set, and mints the {@link ClientRealtimeSessionConfig}.
+     *
+     * Returns a failure result (never throws) when no Realtime model/key resolves or the provider
+     * cannot mint a client-direct session.
+     *
+     * @param input The co-agent/target/session inputs.
+     * @param contextUser The calling user (threaded to metadata + memory retrieval).
+     * @param provider The request-scoped metadata provider.
+     * @returns The prep result (Success + ClientConfig/SessionParams, or Success: false + ErrorMessage).
+     */
+    PrepareClientSession(input: PrepareClientSessionInput, contextUser: UserInfo, provider: IMetadataProvider): Promise<RealtimeClientSessionPrepResult>;
+    /**
+     * 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
+     * identically, with **zero host-local re-implementation**. This is the Phase 2 counterpart to
+     * {@link PrepareClientSession}: the browser relays tool calls back over GraphQL to `ExecuteRelayedTool`,
+     * whereas here the server holds the live {@link IRealtimeSession} and we wire its `OnToolCall` directly to
+     * the SAME {@link ExecuteRelayedTool} (so `invoke-target-agent` runs the target via `AgentRunner`, nests
+     * under the co-agent run, supports barge-in cancel + paused-run resume — all of it, for free).
+     *
+     * Responsibilities, in order:
+     * 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
+     *    routed through one idempotent finalizer. The bridge teardown calls `Close()`, so the run finalizes
+     *    on graceful end; a dropped socket finalizes via `OnClose`.
+     *
+     * @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, …).
+     * @param prep The successful {@link PrepareRealtimeSessionParams} result (CoAgent + Resolution).
+     * @param contextUser The calling user (threaded into observability + delegated runs).
+     * @param provider The request-scoped metadata provider.
+     * @returns A {@link BridgeRealtimeRuntime} the bridge holds for the session lifetime.
+     */
+    WireBridgeRealtimeSession(session: IRealtimeSession, input: PrepareClientSessionInput, prep: RealtimeSessionParamsPrep, contextUser: UserInfo, provider: IMetadataProvider): Promise<BridgeRealtimeRuntime>;
+    /**
+     * 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
+     * bridge from hanging on a tool call when prep was incomplete.
+     */
+    private wireBridgeFallbackRuntime;
+    /**
+     * **The single source of truth for realtime session prep.** Builds the {@link RealtimeSessionParams}
+     * for a co-agent voicing a target: resolves the co-agent, the effective config via the full precedence
+     * cascade (type-default < co-agent < **target** < runtime override), the realtime model, then assembles
+     * the companion system prompt (**first-person as the TARGET** — this is what gives every host the right
+     * identity), the stable tool set (**always including `invoke-target-agent`**), voice, and memory.
+     *
+     * EVERY realtime host consumes this — native chat via {@link PrepareClientSession} → `CreateClientSession`,
+     * and the server-bridged hosts (LiveKit, future Zoom/Teams) via `StartSession`. Hosts differ ONLY in how
+     * they OPEN the session and their media transport; identity/precedence/prompt/tools live here, once. Do
+     * NOT re-implement this in a host. See `plans/realtime/realtime-core-host-convergence.md`.
+     *
+     * Pure-ish and side-effect-free (no session opened, no observability run created) — those are the
+     * opener's concern. Never throws — returns `Success: false` on failure.
+     *
+     * @param input The co-agent/target/session inputs (the runtime override rides `ConfigOverridesJson`).
+     * @param contextUser The calling user (threaded to metadata + memory retrieval).
+     * @param provider The request-scoped metadata provider.
+     * @returns The prep result: `Success` + co-agent/resolution/effective-config/session-params, or `Success: false`.
+     */
+    PrepareRealtimeSessionParams(input: PrepareClientSessionInput, contextUser: UserInfo, provider: IMetadataProvider): Promise<RealtimeSessionParamsPrep>;
+    /**
+     * 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`.
+     *
+     * @param coAgent The resolved co-agent.
+     * @param overridesJson The pre-authorized runtime override layer, when present.
+     * @param targetAgent The TARGET agent being voiced, when distinct from the co-agent — contributes the
+     *   per-voiced-agent layer (above the co-agent, below the runtime override). Omit when there is none.
+     * @returns The normalized effective configuration (possibly empty, never `null`).
+     */
+    protected resolveEffectiveConfig(coAgent: MJAIAgentEntityExtended, overridesJson?: string, targetAgent?: MJAIAgentEntityExtended | null): RealtimeCoAgentConfig;
+    /**
+     * 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`.
+     */
+    protected getAgentTypeDefaultConfiguration(coAgent: MJAIAgentEntityExtended): string | null;
+    /**
+     * 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.
+     *
+     * @param coAgent The resolved co-agent (its id stamps `AgentID` on both runs).
+     * @param promptID The co-agent system prompt id, or `null` to skip the prompt run + run step.
+     * @param modelID The resolved realtime model id (stamps the prompt run's `ModelID`).
+     * @param userID Optional owning user id for the agent run.
+     * @param agentSessionID The session id grouping this voice session's runs.
+     * @param contextUser The calling user.
+     * @param provider The request-scoped metadata provider.
+     * @returns The `{ CoAgentRunID, PromptRunID, CoAgentRunStepID }` ids, or `null` when the agent run failed.
+     */
+    protected createCoAgentObservabilityRun(coAgent: MJAIAgentEntityExtended, promptID: string | null, modelID: string, vendorID: string, userID: string | undefined, agentSessionID: string, contextUser: UserInfo, provider: IMetadataProvider, conversationID?: string): Promise<{
+        CoAgentRunID: string;
+        PromptRunID?: string;
+        CoAgentRunStepID?: string;
+    } | null>;
+    /**
+     * Creates the co-agent `AIAgentRun` row (Status `Running`). Returns its id, or `null` (logging
+     * `CompleteMessage`) when the save fails.
+     */
+    private createCoAgentRun;
+    /**
+     * 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
+     * prompt's run history (`PromptID`) and in agent-scoped prompt-run views. Returns its id, or
+     * `null` when `promptID` is absent (skipped) or the save fails (logged).
+     */
+    private createCoAgentPromptRun;
+    /**
+     * Creates the single `MJ: AI Agent Run Steps` row for the co-agent observability run — the
+     * realtime session has no iterative loop, so its Timeline carries exactly one step
+     * representing the session's system prompt (StepNumber 1, StepType `Prompt`, Status `Running`,
+     * `TargetID` = the system `AIPrompt`, `TargetLogID` = the linked `AIPromptRun` when one was
+     * created). Skipped (returns `null`) when no system prompt resolved. Best-effort: a save
+     * failure is logged and returns `null` — it never breaks the session.
+     */
+    private createCoAgentRunStep;
+    /**
+     * Finalizes the server-side co-agent observability records when a voice session ends. Loads
+     * each (when its id is supplied) and, **only if it is still `Running`**, sets it to `Completed`
+     * (or `Failed` when `success` is false) with a `CompletedAt` + `Success` stamp. Idempotent and
+     * tolerant: a missing/already-finalized record is a no-op; a load/save failure is logged,
+     * never thrown.
+     *
+     * @param coAgentRunID The co-agent run id, or `null` to skip.
+     * @param promptRunID The co-agent prompt run id, or `null` to skip.
+     * @param contextUser The calling user.
+     * @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.
+     */
+    FinalizeCoAgentRun(coAgentRunID: string | null, promptRunID: string | null, contextUser: UserInfo, provider: IMetadataProvider, success?: boolean, coAgentRunStepID?: string | null): Promise<void>;
+    /**
+     * 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,
+     * where the `Close()`-wrapped finalizer never ran. This is the by-`AgentSessionID` analogue of
+     * {@link FinalizeCoAgentRun}: the same-process path already knows its run ids (no query), but here that
+     * state died with the prior process, so we locate the session's TOP-LEVEL co-agent run (delegated target
+     * runs nest under it and finalize on their own runner) and finalize it + its prompt run + step via the
+     * same idempotent helpers. A clean teardown already marked them `Completed`, so this finds nothing.
+     *
+     * `MJ: AI Agent Runs` is a high-volume transactional table no engine caches, so a narrow ids-only query
+     * is the right tool (not a cache reuse). Tolerant — never throws.
+     *
+     * @param agentSessionID The agent session whose dangling co-agent runs to finalize.
+     * @param success Mark them `Completed` (true) or `Failed` (false).
+     * @param contextUser The user the writes run as.
+     * @param provider The request-scoped metadata provider.
+     * @returns The number of co-agent runs finalized (0 when none were dangling).
+     */
+    FinalizeCoAgentRunsBySession(agentSessionID: string, success: boolean, contextUser: UserInfo, provider: IMetadataProvider): Promise<number>;
+    /** Finds the still-`Running` prompt-run + run-step ids for a co-agent run (orphan finalize path). */
+    private findCoAgentChildLogIds;
+    /** Escapes single quotes for safe embedding in an `ExtraFilter` literal. */
+    private escapeSqlLiteral;
+    /** Loads + finalizes the co-agent `AIAgentRun` if still `Running`. 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.
+     */
+    private finalizeRunStep;
+    /** Loads + finalizes the co-agent `AIPromptRun` if still `Running`. Tolerant: logs, never throws. */
+    private finalizePromptRun;
+    /**
+     * Appends (or replaces) one transcript turn onto the co-agent's long-lived `AIPromptRun.Messages`,
+     * so the realtime co-agent's conversation is captured on its run exactly like every other MJ agent
+     * run — closing the observability gap where the run held only token totals, never the turns. The
+     * run viewer can then show what the co-agent heard and said. Mirrors {@link accumulatePromptRunUsage}'s
+     * load/append/save pattern; best-effort and tolerant (logs, never throws).
+     *
+     * `replacePrevious` swaps the last same-role message instead of appending — the streaming-correction
+     * case (an interim assistant turn finalized into its full text). The stored shape is the standard
+     * chat-message array (`[{ role, content }, …]`) the rest of MJ already reads from `Messages`.
+     *
+     * NOTE: load-append-save carries the same benign race as usage accumulation; realtime turns are
+     * sequential per session so collisions are rare. A dedicated child turn-row entity would remove the
+     * race (and the blob rewrite) entirely — a future increment. Tool-call turns (the browser_ and
+     * Whiteboard_ channel tools) are a separate increment that requires the client to relay them.
+     *
+     * @returns `true` when the turn was persisted onto the prompt run.
+     */
+    AppendPromptRunMessage(promptRunID: string, role: 'user' | 'assistant' | 'system', content: string, replacePrevious: boolean, contextUser: UserInfo, provider: IMetadataProvider): Promise<boolean>;
+    /**
+     * Accumulates relayed usage DELTAS onto the co-agent `AIPromptRun`'s `TokensPrompt` / `TokensCompletion`
+     * (recomputing `TokensUsed`). Serialized against {@link AppendPromptRunMessage} on the same run so the
+     * high-frequency usage checkpoint never overwrites freshly-appended transcript turns (and vice-versa).
+     * Best-effort: load/save failures log and return `false`, never throw.
+     *
+     * @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).
+     * @returns `true` when the accumulated usage was persisted.
+     */
+    AccumulatePromptRunUsage(promptRunID: string, inputDelta: number, outputDelta: number, contextUser: UserInfo, provider: IMetadataProvider): Promise<boolean>;
+    /** Parses the prompt run's `Messages` JSON into a mutable chat-message array (tolerant: `[]` on empty/malformed). */
+    private parsePromptRunMessages;
+    /**
+     * Executes a single tool call relayed from the browser and returns its serialized result.
+     *
+     * Builds a {@link RealtimeToolBroker} whose `DelegateToTarget` runs the target agent (threading
+     * the abort signal, parent run, and session id) and whose `ExecuteTool` returns a structured
+     * "not available" result for non-target tools (action wiring is a later phase). The broker
+     * routes the call and always resolves with structured JSON — failures become `tool_response`
+     * errors the model can narrate rather than thrown exceptions.
+     *
+     * @param input The relayed tool call plus delegation linkage.
+     * @param contextUser The calling user (threaded into the delegated agent run).
+     * @param provider The request-scoped metadata provider (threaded into the delegated agent run).
+     * @returns `{ ResultJson, Success, PausedRunID?, Artifacts? }` — the serialized tool result for
+     *   the browser to relay back, the paused run id when the delegated target agent paused awaiting
+     *   feedback (so the resolver can persist it and resume that run on the next answer), and the
+     *   artifacts the delegated run produced (so the resolver can junction-link them into the
+     *   session's conversation history — the same info is embedded in `ResultJson` for the client).
+     */
+    ExecuteRelayedTool(input: ExecuteRelayedToolInput, contextUser: UserInfo, provider: IMetadataProvider): Promise<{
+        ResultJson: string;
+        Success: boolean;
+        PausedRunID?: string;
+        Artifacts?: DelegatedRunArtifact[];
+    }>;
+    /**
+     * Aborts in-flight relayed delegations for a session — the server half of the client-direct
+     * CANCEL channel (see the registry note on {@link inFlightDelegations}).
+     *
+     * @param agentSessionID The session whose in-flight delegations to abort.
+     * @param callID When supplied, only the delegation for this specific call is aborted; when
+     *   omitted, EVERY in-flight delegation for the session is aborted.
+     * @returns The number of in-flight delegations aborted. **Tolerant by design**: an unknown
+     *   session, an unknown call id, or a session with nothing in flight returns `0` — never throws
+     *   (the call the user wanted dead may simply have finished already, which is a fine outcome).
+     */
+    CancelInFlightDelegations(agentSessionID: string, callID?: string): number;
+    /** Normalized (trim + lowercase) registry key so UUID casing differences can't split entries. */
+    private registryKey;
+    /** Creates + registers the abort controller for one in-flight relayed call. */
+    private registerInFlightDelegation;
+    /**
+     * Removes one call's registry entry on completion — but only when the stored controller is
+     * STILL the one this execution registered (a cancel may already have removed it, and a
+     * same-callID retry may have replaced it).
+     */
+    private unregisterInFlightDelegation;
+    /**
+     * Ensures {@link AIEngine} metadata is loaded before resolution. **Overridable seam** so tests
+     * can skip the DB-backed config load.
+     *
+     * @param contextUser The calling user.
+     * @param provider The request-scoped metadata provider.
+     */
+    protected configureEngine(contextUser: UserInfo, provider: IMetadataProvider): Promise<void>;
+    /**
+     * Resolves the co-agent from either the supplied entity or its id (from cached metadata).
+     *
+     * @param input The prepare-session input.
+     * @returns The co-agent entity, or `null` when neither form resolves.
+     */
+    protected resolveCoAgent(input: PrepareClientSessionInput): MJAIAgentEntityExtended | null;
+    /**
+     * Resolves the realtime model for a session, honoring an explicit user choice when present.
+     *
+     * - With {@link PrepareClientSessionInput.PreferredModelID}: resolve THAT model strictly via
+     *   {@link 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
+     *   {@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.
+     *
+     * @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`).
+     * @returns The resolution outcome (resolution or failure reason).
+     */
+    protected resolveModelForSession(input: PrepareClientSessionInput, coAgent: MJAIAgentEntityExtended, effectiveConfig?: RealtimeCoAgentConfig): Promise<RealtimeModelResolutionOutcome>;
+    /**
+     * 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 ({@link resolvePreferredRealtimeModel}), which fails loud.
+     *
+     * @param effectiveConfig The resolved effective configuration.
+     * @returns The resolution, or `null` when no preference is configured or it can't be satisfied.
+     */
+    protected resolveConfiguredModelPreference(effectiveConfig?: RealtimeCoAgentConfig): 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.
+     *
+     * @param preference The `MJ: AI Models` ID or Name.
+     * @returns The model entity, or `null`.
+     */
+    protected findModelByIDOrName(preference: string): MJAIModelEntityExtended | null;
+    /**
+     * 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.
+     *
+     * @param preferredModelID The `MJ: AI Models.ID` the user chose.
+     * @returns The resolution outcome (resolution or a specific failure reason).
+     */
+    protected resolvePreferredRealtimeModel(preferredModelID: string): RealtimeModelResolutionOutcome;
+    /**
+     * Looks up a model by id in {@link AIEngine}'s cached models. **Overridable seam** for tests.
+     *
+     * @param modelID The `MJ: AI Models.ID` to find.
+     * @returns The model entity, or `null` when not present.
+     */
+    protected findModelByID(modelID: string): MJAIModelEntityExtended | null;
+    /** True when the model's denormalized `AIModelType` name is `Realtime` (case/whitespace-insensitive). */
+    private isRealtimeModel;
+    /**
+     * 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.
+     *
+     * @param coAgent The co-agent being voiced (reserved for future per-agent model preference).
+     * @returns The resolved model + identifiers, or `null`.
+     */
+    protected resolveRealtimeModel(coAgent: MJAIAgentEntityExtended): 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.
+     *
+     * @param model The chosen model entity.
+     * @returns The full resolution, or `null` when no vendor/key/driver can be satisfied.
+     */
+    protected resolveVendorAndInstantiate(model: MJAIModelEntityExtended): RealtimeModelResolution | null;
+    /**
+     * 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.
+     *
+     * @param driverClass The vendor's `DriverClass`.
+     * @returns The API key, or a falsy value when none is configured.
+     */
+    protected getAPIKeyForDriver(driverClass: string): string | undefined;
+    /**
+     * Instantiates the realtime driver for a vendor driver class via the ClassFactory.
+     * **Overridable seam** so tests can return a mock driver.
+     *
+     * @param driverClass The vendor's `DriverClass` (the ClassFactory key).
+     * @param apiKey The resolved API key (constructor argument).
+     * @returns The driver instance, or `null` when the factory cannot create one.
+     */
+    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.
+     * 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.
+     *
+     * @param coAgent The co-agent (reserved for future per-agent model preference).
+     * @returns The candidate models in resolution order (empty array when none are active).
+     */
+    private selectRealtimeModelCandidates;
+    /**
+     * Selects the highest-priority active vendor for a model whose `DriverClass` has a resolvable
+     * API key. Mirrors `BaseAgent.selectRealtimeVendor`.
+     *
+     * @param modelID The chosen model's id.
+     * @returns The vendor driver/api identifiers, or `null` when none has a usable key.
+     */
+    protected selectRealtimeVendor(modelID: string): {
+        VendorID: string;
+        DriverClass: string;
+        APIName: string;
+    } | null;
+    /**
+     * Resolves the DB-driven progress-narration instruction template: the Active `MJ: AI Prompts`
+     * row named {@link RealtimeClientSessionService.NarrationPromptName}, read from
+     * {@link AIEngine}'s cached prompts. When the current name is absent, falls back to the
+     * DEPRECATED {@link 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.
+     *
+     * @returns The template text (containing a `{{ progressMessage }}` placeholder), or `null`.
+     */
+    protected resolveNarrationInstructionsTemplate(): string | null;
+    /**
+     * Builds the {@link RealtimeSessionParams} for the client-direct session: the companion system
+     * prompt plus the stable, target-independent tool set.
+     *
+     * @param input The prepare-session input.
+     * @param coAgent The resolved co-agent.
+     * @param modelApiName The vendor API name of the resolved realtime model.
+     * @param contextUser The calling user.
+     * @param provider The request-scoped metadata provider.
+     * @param effectiveConfig The resolved effective configuration (voice persona + provider settings).
+     * @param driverClass The resolved vendor's DriverClass — matches per-provider voice settings.
+     * @returns The assembled session params.
+     */
+    protected buildSessionParams(input: PrepareClientSessionInput, coAgent: MJAIAgentEntityExtended, modelApiName: string, contextUser: UserInfo, provider: IMetadataProvider, effectiveConfig?: RealtimeCoAgentConfig, driverClass?: string): Promise<RealtimeSessionParams>;
+    /**
+     * 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 {@link 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.
+     *
+     * @param input The prepare-session input (carries the runtime config bag).
+     * @param effectiveConfig The resolved effective configuration.
+     * @param driverClass The resolved vendor's DriverClass.
+     * @returns The merged config bag, or `undefined` when nothing contributes.
+     */
+    protected buildSessionConfigBag(input: PrepareClientSessionInput, effectiveConfig?: RealtimeCoAgentConfig, driverClass?: string): JSONObject | undefined;
+    /**
+     * 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.
+     *
+     * @param input The prepare-session input.
+     * @param coAgent The resolved co-agent.
+     * @param contextUser The calling user.
+     * @param provider The request-scoped metadata provider.
+     * @param effectiveConfig The resolved effective configuration (voice persona source).
+     * @returns The concatenated system prompt (never empty — the framing is always present).
+     */
+    protected buildCompanionSystemPrompt(input: PrepareClientSessionInput, coAgent: MJAIAgentEntityExtended, contextUser: UserInfo, provider: IMetadataProvider, effectiveConfig?: RealtimeCoAgentConfig): Promise<string>;
+    /**
+     * Builds the **meeting-mode** discipline clause — present only for a multi-agent meeting session
+     * ({@link 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`.
+     *
+     * @param input The prepare-session input (carries the meeting flag + self names).
+     * @returns The meeting clause, or `''` for a non-meeting session.
+     */
+    protected buildMeetingFraming(input: PrepareClientSessionInput): string;
+    /**
+     * 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
+     * ({@link 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.
+     *
+     * @param extraTools The client-supplied channel tools, when any.
+     * @returns The exception clause (leading space included), or '' when there are no extra tools.
+     */
+    protected buildInteractiveSurfaceFraming(extraTools?: RealtimeToolDefinition[]): string;
+    /**
+     * Frames the prior-leg transcript (when a session resumes via `lastSessionId`) as a clearly
+     * labeled PRIOR-CONVERSATION section of the system prompt, so the model REMEMBERS the last
+     * live session rather than greeting the user cold. The transport layer supplies the
+     * already-capped, role-tagged lines (see {@link PrepareClientSessionInput.PriorTranscript});
+     * this method only adds the framing. Empty/whitespace input yields an empty section.
+     *
+     * @param priorTranscript The role-tagged transcript lines, or undefined.
+     * @returns The framed section, or empty string when there is nothing to frame.
+     */
+    private formatPriorTranscript;
+    /**
+     * Resolves the target agent entity from cached metadata.
+     *
+     * @param targetAgentID The target agent id.
+     * @returns The target agent entity, or `null` when not found.
+     */
+    protected resolveTargetAgent(targetAgentID: string): MJAIAgentEntityExtended | null;
+    /**
+     * Reads the co-agent's own system prompt text from its highest-priority active agent prompt,
+     * mirroring `BaseAgent.loadAgentConfiguration`'s child-prompt resolution.
+     *
+     * @param coAgent The resolved co-agent.
+     * @returns The co-agent's system prompt template text, or empty string when none is configured.
+     */
+    protected getCoAgentSystemPromptText(coAgent: MJAIAgentEntityExtended): string;
+    /**
+     * Resolves the co-agent's highest-priority active system prompt, returning both its template
+     * text and its prompt id. The id is surfaced so {@link PrepareClientSession} can create a linked
+     * co-agent `AIPromptRun` for observability. Mirrors `BaseAgent.loadAgentConfiguration`'s
+     * child-prompt resolution.
+     *
+     * @param coAgent The resolved co-agent.
+     * @returns The prompt text + id, or `{ Text: '', PromptID: null }` when none is configured.
+     */
+    protected resolveCoAgentSystemPrompt(coAgent: MJAIAgentEntityExtended): CoAgentSystemPromptResolution;
+    /**
+     * Formats the target agent's identity + capabilities block for the system prompt.
+     *
+     * @param target The target agent, or `null`.
+     * @returns The formatted block, or empty string when no target resolved.
+     */
+    private formatTargetIdentity;
+    /**
+     * Formats prior conversation history as a plain-text block for the system prompt.
+     *
+     * @param messages The conversation messages, or undefined.
+     * @returns The formatted history block, or empty string when there is none.
+     */
+    private formatConversationHistory;
+    /**
+     * Assembles the same memory/context block a loop agent injects, reusing
+     * {@link 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.
+     *
+     * @param input The prepare-session input.
+     * @param coAgent The resolved co-agent.
+     * @param contextUser The calling user.
+     * @returns The concatenated context text (empty string when nothing was injected).
+     */
+    protected assembleMemoryContext(input: PrepareClientSessionInput, coAgent: MJAIAgentEntityExtended, contextUser: UserInfo): Promise<string>;
+    /**
+     * 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.
+     *
+     * @param extraTools Optional additional target-independent tools.
+     * @returns The tools to register at session start.
+     */
+    protected buildStableToolSet(extraTools?: RealtimeToolDefinition[]): RealtimeToolDefinition[];
+    /**
+     * Builds the {@link RealtimeToolBroker} for a relayed tool call, wiring `DelegateToTarget` to a
+     * target-agent run and `ExecuteTool` to a structured "not available" placeholder.
+     *
+     * @param input The relayed tool input.
+     * @param contextUser The calling user.
+     * @param provider The request-scoped metadata provider.
+     * @returns The constructed broker.
+     */
+    protected buildToolBroker(input: ExecuteRelayedToolInput, contextUser: UserInfo, provider: IMetadataProvider): RealtimeToolBroker;
+    /**
+     * Delegates an `invoke-target-agent` call to the target agent via {@link 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`.
+     *
+     * @param input The relayed tool input (target id + linkage).
+     * @param request The broker's delegation request (call id + arguments + abort signal).
+     * @param contextUser The calling user.
+     * @param provider The request-scoped metadata provider.
+     * @returns The delegated result for the model's tool_response.
+     */
+    protected delegateToTarget(input: ExecuteRelayedToolInput, request: DelegateToTargetRequest, contextUser: UserInfo, provider: IMetadataProvider): Promise<DelegatedResult>;
+    /**
+     * 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 {@link 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.
+     *
+     * @param result The delegated agent execution result.
+     * @param contextUser The calling user.
+     * @param provider The request-scoped metadata provider.
+     * @returns The produced artifact descriptor(s), or `undefined` when none were created.
+     */
+    protected createDelegatedRunArtifacts(result: ExecuteAgentResult, contextUser: UserInfo, provider: IMetadataProvider): Promise<DelegatedRunArtifact[] | undefined>;
+    /**
+     * 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 {@link createDelegatedRunArtifacts}' eligibility
+     * guards without a DB.
+     *
+     * @param result The delegated agent execution result (payload + agentRun).
+     * @param contextUser The calling user.
+     * @param provider The request-scoped metadata provider.
+     * @returns The produced artifact descriptor(s), or `undefined`.
+     */
+    protected processRunArtifacts(result: ExecuteAgentResult, contextUser: UserInfo, provider: IMetadataProvider): Promise<DelegatedRunArtifact[] | undefined>;
+    /**
+     * 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.
+     * 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 request The broker's delegation request (call id + arguments + abort signal).
+     * @param target The resolved target agent.
+     * @param contextUser The calling user.
+     * @param provider The request-scoped metadata provider.
+     * @returns The agent execution result.
+     */
+    private runDelegatedAgent;
+    /**
+     * Maps an {@link ExecuteAgentResult} onto the broker's {@link DelegatedResult}, special-casing a
+     * run that paused awaiting feedback. An `AwaitingFeedback` run is a valid intermediate outcome,
+     * not an error: we return its clarifying QUESTION (the run's `Message`) as the tool Output —
+     * phrased so the realtime model relays it as a question to the user — set `Success: true`, and
+     * surface the paused run id so the resolver can resume that run on the user's next answer.
+     *
+     * @param callID The provider call id this result corresponds to.
+     * @param result The agent execution result.
+     * @param artifacts Artifacts the run produced (from {@link createDelegatedRunArtifacts}),
+     *   threaded into the result so the broker serializes them for the call overlay.
+     * @returns The delegated result for the model's tool_response.
+     */
+    private buildDelegatedResult;
+    /**
+     * Loads the co-agent run entity behind {@link 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).
+     *
+     * @param parentRunID The co-agent run id, or undefined.
+     * @param contextUser The calling user.
+     * @param provider The request-scoped metadata provider.
+     * @returns The loaded parent run entity, or `null`.
+     */
+    protected loadParentRun(parentRunID: string | undefined, contextUser: UserInfo, provider: IMetadataProvider): Promise<MJAIAgentRunEntityExtended | null>;
+    /**
+     * 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.
+     *
+     * @param call The non-target tool call.
+     * @returns A failed {@link ToolExecutionResult} the model can narrate.
+     */
+    protected executeNonTargetTool(call: RealtimeToolCall): Promise<ToolExecutionResult>;
+    /**
+     * Parses the natural-language request text out of an `invoke-target-agent` call's arguments.
+     * Falls back to the raw argument string when it is not the expected `{ request: string }` JSON.
+     *
+     * @param argumentsJson The raw arguments string emitted by the model.
+     * @returns The request text to hand to the target agent.
+     */
+    private parseDelegateRequestText;
+    /**
+     * Combines the broker's per-call abort signal with an optional caller-supplied signal so either
+     * source can cancel the delegated run. Returns the broker signal alone when no caller signal is
+     * present (the common case), avoiding an unnecessary controller.
+     *
+     * @param brokerSignal The broker-owned per-call abort signal (always present).
+     * @param callerSignal An optional caller signal (e.g. a request-scoped barge-in).
+     * @returns A single abort signal that fires when either source aborts.
+     */
+    private combineSignals;
+    /**
+     * The clear, actionable message returned when no usable Realtime model can be resolved.
+     *
+     * @returns The failure message.
+     */
+    private noModelMessage;
+}
+//# sourceMappingURL=realtime-client-session-service.d.ts.map