@memberjunction/server 5.40.2 → 5.41.0

package/dist/resolvers/RealtimeClientSessionResolver.d.ts

@@ -0,0 +1,688 @@
+/**
+ * @fileoverview GraphQL resolvers for the CLIENT-DIRECT realtime voice topology (P5b-ii).
+ *
+ * These resolvers are **thin**: they wire two already-built pieces together —
+ * {@link RealtimeClientSessionService} (in `@memberjunction/ai-agents`, the server-side half of the
+ * client-direct contract) and {@link SessionManager} (the durable `AIAgentSession` record manager) —
+ * over a request's `contextUser` + request-scoped `IMetadataProvider`.
+ *
+ * In the client-direct topology the browser opens its OWN provider socket (e.g. WebRTC) using a
+ * server-minted ephemeral token, but the server retains authority over the system prompt + tool set
+ * and **executes** every tool call the browser relays back. The three mutations here cover the MVP:
+ *
+ * 1. {@link RealtimeClientSessionResolver.StartRealtimeClientSession} — authorize, create the
+ *    session (storing the target agent id server-side, authoritatively), mint the ephemeral config.
+ * 2. {@link RealtimeClientSessionResolver.ExecuteRealtimeSessionTool} — execute a relayed tool call,
+ *    reading the target agent id from the session (NOT the client) so the browser can't swap targets.
+ * 3. {@link RealtimeClientSessionResolver.RelayRealtimeTranscript} — persist a transcript turn as a
+ *    `Conversation Detail`.
+ *
+ * Authorization model:
+ * - **Start**: the caller must have `CanRun` on the *target* agent (the Realtime Co-Agent is an internal
+ *   orchestration agent, so the meaningful gate is the agent doing the real work).
+ * - **Execute / Relay**: inbound ownership — the session's `UserID` must equal `contextUser.ID`.
+ *
+ * @module @memberjunction/server
+ */
+import { PubSubEngine } from 'type-graphql';
+import { AppContext } from '../types.js';
+import { ResolverBase } from '../generic/ResolverBase.js';
+/**
+ * Result of {@link RealtimeClientSessionResolver.StartRealtimeClientSession} — everything the
+ * browser needs to open its own provider socket plus the durable session linkage.
+ */
+export declare class StartRealtimeClientSessionResult {
+    /** ID of the newly created `AIAgentSession` record. */
+    AgentSessionId: string;
+    /** ID of the conversation the session is attached to (supplied or freshly created). */
+    ConversationId: string;
+    /** The provider that minted the credential (e.g. `'openai'`). */
+    Provider: string;
+    /** The provider realtime model id the session is scoped to (e.g. `gpt-realtime`). */
+    Model: string;
+    /** The short-lived client secret the browser presents to the provider to authenticate. */
+    EphemeralToken: string;
+    /** ISO-8601 timestamp at which {@link StartRealtimeClientSessionResult.EphemeralToken} expires. */
+    ExpiresAt: string;
+    /** JSON string of the provider-native session config the browser applies verbatim. */
+    SessionConfigJson: string;
+    /** Display name of the realtime model the session uses (e.g. `GPT Realtime 2`). Null when unknown. */
+    ModelName?: string;
+    /**
+     * DB-driven progress-narration instruction template (contains a `{{ progressMessage }}`
+     * placeholder). Null when the narration prompt is not present in this deployment's metadata —
+     * the browser falls back to its built-in narration text.
+     */
+    NarrationInstructionsTemplate?: string;
+    /**
+     * JSON object string keyed by channel NAME mapping to that channel's persisted state JSON from
+     * the caller's PRIOR session (`lastSessionId`) — e.g. `{"Whiteboard":"{...board scene...}"}`.
+     * Null when no `lastSessionId` was supplied, the prior session has no persisted channel state,
+     * the prior session is not owned by the caller, or the restore failed for any reason (restore
+     * is strictly best-effort — a session start NEVER fails because of it).
+     */
+    PriorChannelStatesJson?: string;
+    /**
+     * The effective narration pace (`realtime.narration.paceMs` from the co-agent's effective
+     * configuration) — minimum gap in ms between spoken progress updates. Null when not
+     * configured (the browser uses its built-in pacing default). In the client-direct topology
+     * narration pacing is enforced CLIENT-side, so the server surfaces the configured value here.
+     */
+    NarrationPaceMs?: number;
+    /**
+     * JSON of the RESOLVED effective realtime configuration for this session (type
+     * `DefaultConfiguration` ← agent `TypeConfiguration` ← authorized runtime overrides,
+     * deep-merged + normalized server-side). The browser uses it to apply client-side concerns
+     * (e.g. per-provider voice settings consumed by client drivers, narration pacing). Null only
+     * when the prepare service did not resolve a config (back-compat).
+     */
+    EffectiveConfigJson?: string;
+}
+/**
+ * Result of {@link RealtimeClientSessionResolver.SaveSessionChannelArtifact} — a structured
+ * success/failure envelope (graceful failures like a missing artifact type must not throw).
+ */
+export declare class SaveSessionChannelArtifactResult {
+    /** True when the artifact + first version were both persisted. */
+    Success: boolean;
+    /** Human-readable failure reason. Null on success. */
+    ErrorMessage?: string;
+    /** ID of the created `MJ: Artifacts` row. Null when creation failed before the header saved. */
+    ArtifactID?: string;
+    /** ID of the created `MJ: Artifact Versions` row (version 1). Null on failure. */
+    ArtifactVersionID?: string;
+    /**
+     * True when the version was also linked into conversation history via a
+     * `MJ: Conversation Detail Artifacts` junction row. False when the session has no
+     * conversation, no conversation detail was stamped with this session id yet, or the
+     * (best-effort) junction save failed — none of which fail the overall save.
+     */
+    ConversationDetailLinked: boolean;
+}
+/**
+ * Result of {@link RealtimeClientSessionResolver.CancelRealtimeSessionTool} — a structured
+ * success/failure envelope, mirroring {@link SaveSessionChannelArtifactResult}: tolerated
+ * problems (an unexpected registry error) come back as `Success: false`, never a throw, while
+ * authn/ownership violations still throw like the sibling mutations.
+ */
+export declare class CancelRealtimeSessionToolResult {
+    /**
+     * How many in-flight delegations were aborted. `0` is a legitimate SUCCESS outcome — the
+     * work the user wanted dead may simply have finished (or never started) already.
+     */
+    AbortedCount: number;
+    /** True when the cancel request was processed (even when nothing was in flight). */
+    Success: boolean;
+    /** Human-readable failure reason. Null on success. */
+    ErrorMessage?: string;
+}
+/**
+ * Resolver for the client-direct realtime voice topology. A single {@link SessionManager} and a
+ * single {@link RealtimeClientSessionService} are shared across requests — neither holds per-user or
+ * per-provider state; every method is passed the request `contextUser` + provider explicitly.
+ */
+export declare class RealtimeClientSessionResolver extends ResolverBase {
+    private readonly sessionManager;
+    private readonly clientSessionService;
+    /**
+     * Start a client-direct realtime voice session targeting `targetAgentId`.
+     *
+     * Flow:
+     * 1. Authorize — the caller must have `CanRun` on the **target** agent; denial throws and no
+     *    session is created.
+     * 2. Resolve the co-agent id via the metadata-driven resolution chain (runtime `coAgentId` →
+     *    agent's `DefaultCoAgentID` → type-level `AIAgentCoAgent` default row → global Realtime Co-Agent) —
+     *    see {@link RealtimeClientSessionResolver.resolveCoAgentID} for the full contract.
+     * 3. Create the durable `AIAgentSession` (run by the co-agent), storing `targetAgentID` in its
+     *    config server-side — this is the authoritative target for all later relays.
+     * 4. Mint the {@link import('@memberjunction/ai').ClientRealtimeSessionConfig} via the service.
+     *    On failure the just-created session is closed so no half-open session leaks.
+     *
+     * **SECURITY NOTE — `clientToolsJson`:** these are CLIENT-EXECUTED UI tools (e.g. the live
+     * whiteboard's `Whiteboard.*` surface). The server only *declares* them to the realtime model
+     * so it can call them — the server NEVER executes them, and a relayed call for one of these
+     * names falls into the standard "not available" path on the server side. They grant no
+     * server-side capability whatsoever; server-executed tools remain exclusively server-declared
+     * (`invoke-target-agent` + future action wiring). The declarations are still validated
+     * (count cap, size cap, per-tool shape) so a hostile client can't bloat the session config.
+     *
+     * @param targetAgentId The agent the co-agent voices. OPTIONAL when the resolved co-agent
+     *   has pairing rows with an `IsDefault` target (`MJ: AI Agent Co Agents`) — the default
+     *   pairing stands in. Required for a universal co-agent (zero pairing rows). When the
+     *   co-agent HAS pairing rows, a supplied target must be in that list (clear error otherwise).
+     * @param coAgentId Optional EXPLICIT co-agent choice (`MJ: AI Agents.ID` of an Active,
+     *   Realtime-type agent). When set, the server uses exactly that co-agent and FAILS with a
+     *   clear reason if it can't (no silent fallback — mirroring `preferredModelId`'s contract).
+     *   Omit to let metadata drive the choice: the target agent's `DefaultCoAgentID`, then the
+     *   type-level `AIAgentCoAgent` default row for its agent type, then the global Realtime Co-Agent.
+     * @param configOverridesJson Optional RUNTIME configuration-override layer (the most-specific
+     *   layer of the effective-config merge: type `DefaultConfiguration` ← agent
+     *   `TypeConfiguration` ← this). **Authorization-gated**: requires the
+     *   `Realtime: Advanced Session Controls` authorization — unauthorized callers receive a
+     *   structured rejection (never a silent ignore). Must be a JSON object.
+     *
+     * @returns The ephemeral config + session linkage the browser needs to open its socket.
+     */
+    StartRealtimeClientSession(targetAgentId: string | undefined, { userPayload, providers }: AppContext, conversationId?: string, lastSessionId?: string, preferredModelId?: string, clientToolsJson?: string, coAgentId?: string, configOverridesJson?: string): Promise<StartRealtimeClientSessionResult>;
+    /**
+     * Execute a single tool call the browser relayed from its provider socket and return the
+     * serialized result for the browser to relay back to the model.
+     *
+     * Ownership-gated; the target agent id is read from the **session config** (authoritative), never
+     * from the client. Heartbeats the session on success.
+     *
+     * @returns The serialized tool result JSON.
+     */
+    ExecuteRealtimeSessionTool(agentSessionId: string, callId: string, toolName: string, argsJson: string, { userPayload, providers }: AppContext, pubSub: PubSubEngine): Promise<string>;
+    /**
+     * Builds the `OnProgress` callback threaded into the delegated target-agent run. Each significant
+     * progress event (see {@link SIGNIFICANT_PROGRESS_STEPS}) is published to
+     * {@link PUSH_STATUS_UPDATES_TOPIC} on this user's `sessionId` so the browser can correlate it to
+     * THIS voice session (via `agentSessionID` + `callID`) and feed it to the realtime model to
+     * narrate — distinct from a normal `RunAIAgentResolver` agent-run stream by `resolver`/`type`.
+     */
+    private buildDelegationProgressCallback;
+    /**
+     * Rolls the session's `pendingFeedbackRunID` forward after a relayed tool call. The id we just
+     * consumed (resumed or none) is dropped; a new paused run id is stored only when the run paused
+     * again awaiting feedback. When neither the old nor new value is set, this is a no-op (no save).
+     * Best-effort: a save failure is logged, not thrown.
+     */
+    private updatePendingFeedbackRunID;
+    /**
+     * Persist a transcript turn (user or assistant) as a `Conversation Detail` on the session's
+     * conversation. Ownership-gated; heartbeats the session on success.
+     *
+     * The co-agent observability `AIAgentRun`/`AIPromptRun` are created at session start (see
+     * {@link RealtimeClientSessionResolver.StartRealtimeClientSession}) and finalized on close;
+     * incremental usage telemetry lands on the `AIPromptRun` via
+     * {@link RealtimeClientSessionResolver.RelayRealtimeUsage}. Each persisted turn is ALSO appended
+     * to the co-agent `AIPromptRun.Messages` (best-effort), so the run captures the full conversation
+     * — observability parity with every other MJ agent run, not just token totals.
+     *
+     * @returns `true` when the transcript turn was persisted.
+     */
+    RelayRealtimeTranscript(agentSessionId: string, role: string, text: string, { userPayload, providers }: AppContext, replacesPrevious?: boolean): Promise<boolean>;
+    /**
+     * Maps the relayed transcript role (`'User'`/`'AI'`/`'Assistant'`, case-insensitive) to the
+     * standard chat-message role stored in `AIPromptRun.Messages`. Anything that isn't an explicit
+     * user turn is treated as the assistant (the co-agent's own speech).
+     */
+    private mapTranscriptRoleToChatRole;
+    /**
+     * Relays a co-agent CHANNEL tool-call (browser_ / Whiteboard_ etc.) onto the session's co-agent
+     * AIPromptRun.Messages — run-only observability so the run captures what the co-agent DID, not just
+     * what it said. Deliberately NOT a ConversationDetail turn (the chat thread stays speech-only).
+     * Ownership-gated; best-effort (a missing prompt run / save failure simply returns false).
+     *
+     * @returns `true` when the tool turn was recorded on the run.
+     */
+    RelayRealtimeToolTurn(agentSessionId: string, toolName: string, { userPayload, providers }: AppContext, argsJson?: string, resultJson?: string): Promise<boolean>;
+    /**
+     * Formats a co-agent tool call into a compact, human-readable run line: `🔧 <tool> <args> → <result>`,
+     * clipping args/result so a verbose payload never bloats the Messages blob.
+     */
+    private formatToolTurn;
+    /**
+     * Cancel in-flight relayed tool delegations for a session — the CLIENT-DIRECT cancel channel.
+     *
+     * The browser calls this on an EXPLICIT user cancel (the call overlay's per-card ✕ — a
+     * deliberate host policy: true barge-in alone never aborts delegations, since the narration
+     * design expects the user to keep talking while delegated work runs). The service-side
+     * in-flight registry aborts the matching `AbortController`(s), which fires the delegated
+     * run's `cancellationToken`; the original `ExecuteRealtimeSessionTool` mutation then resolves
+     * with the run's cancelled/failed result through its normal path.
+     *
+     * Ownership-gated like the sibling mutations. A **Closed** session is accepted — a cancel can
+     * legitimately race teardown, and aborting stragglers is exactly what the caller wants then.
+     *
+     * @param callId When supplied, only the delegation for that provider call id is aborted;
+     *   omit to abort ALL in-flight delegations for the session.
+     * @returns A structured {@link CancelRealtimeSessionToolResult}. Tolerant: an unknown call id
+     *   or a session with nothing in flight is `Success: true, AbortedCount: 0` (the work may
+     *   simply have finished already); an unexpected registry error is a structured failure.
+     */
+    CancelRealtimeSessionTool(agentSessionId: string, { userPayload, providers }: AppContext, callId?: string): Promise<CancelRealtimeSessionToolResult>;
+    /**
+     * Relay incremental usage telemetry from the browser's provider socket onto the co-agent's
+     * observability `AIPromptRun` (the run created at session start).
+     *
+     * The browser accumulates the realtime client's `OnUsage` token DELTAS and flushes them here
+     * debounced (~10s) plus once at teardown; this mutation ACCUMULATES the deltas onto the
+     * prompt run's `TokensPrompt` / `TokensCompletion` (and recomputes `TokensUsed`). Status is
+     * deliberately untouched — `FinalizeCoAgentRun` keeps stamping Success/Completed at close,
+     * and a post-close flush still lands (accumulation has no Status gate).
+     *
+     * Ownership-gated like the sibling mutations; a **Closed** session is accepted (the final
+     * teardown flush can land after `CloseAgentSession`). Everything PAST the ownership gate is
+     * best-effort and tolerant: a missing/malformed session config, an absent `promptRunID`
+     * (observability creation was skipped), a failed load, or a failed save all log and return
+     * `false` — usage relay must never break a live call.
+     *
+     * @param inputTokens Input-token DELTA to add (negative/non-finite values are clamped to 0).
+     * @param outputTokens Output-token DELTA to add (negative/non-finite values are clamped to 0).
+     * @returns `true` when the accumulated usage was persisted; `false` on any tolerated failure.
+     */
+    RelayRealtimeUsage(agentSessionId: string, inputTokens: number, outputTokens: number, { userPayload, providers }: AppContext): Promise<boolean>;
+    /** Clamps a relayed token delta: negative / non-finite values become 0. */
+    private clampTokenDelta;
+    /**
+     * Reads the co-agent `AIPromptRun` id from the session config WITHOUT the relay path's
+     * throw-on-missing-target semantics — usage relay is best-effort, so a missing/malformed
+     * config or absent id just logs and returns `null`.
+     */
+    private readPromptRunID;
+    /**
+     * Persist an interactive channel's state of record (e.g. the live whiteboard's serialized
+     * scene) onto the session's `MJ: AI Agent Session Channels` row.
+     *
+     * Flow:
+     * 1. Ownership gate — like the sibling mutations, the session's `UserID` must equal the
+     *    caller's. Unlike Execute/Relay, a **Closed** session is accepted: the client's final
+     *    on-end flush legitimately lands after `CloseAgentSession` has run.
+     * 2. Resolve the channel definition (`MJ: AI Agent Channels`) by `channelName`. When no
+     *    active definition row exists (the deployment hasn't synced the channel seed yet),
+     *    return `false` gracefully and log — never throw for a missing definition.
+     * 3. Offer the payload to the session's SERVER-SIDE channel plugin (the registry row's
+     *    `ServerPluginClass`, held per-session by {@link RealtimeChannelServerHost}) for
+     *    validation/normalization — strictly best-effort: no plugin, a plugin failure, or an
+     *    oversized replacement all fall back to persisting the original payload.
+     * 4. Upsert the session-channel row: create it (Status `Connected`) when missing, store
+     *    the (possibly normalized) state in its `Config` field, and stamp `LastActiveAt`.
+     *
+     * @returns `true` when the state was persisted; `false` on any tolerated failure (missing
+     *   channel definition, oversized state, save failure) — all logged.
+     */
+    SaveSessionChannelState(agentSessionId: string, channelName: string, stateJson: string, { userPayload, providers }: AppContext): Promise<boolean>;
+    /**
+     * Routes a landed channel-state save through the session's server-side channel plugin (when
+     * one resolved at session start) so it can validate/normalize the payload PRE-persistence.
+     * Strictly best-effort: any host/plugin problem — including a replacement that exceeds the
+     * channel-state size cap — falls back to the client's original payload, which already passed
+     * the cap. A plugin can transform a save; it can never lose or block one.
+     */
+    private applyChannelServerPlugin;
+    /**
+     * Persist an interactive channel's current state (e.g. the live whiteboard's board JSON) as a
+     * durable, user-owned **artifact** — distinct from {@link SaveSessionChannelState}, which only
+     * stores the session-scoped state of record. The artifact survives the session and shows up in
+     * the user's artifact library (and, when possible, in the conversation's history).
+     *
+     * Flow:
+     * 1. Ownership gate — like the sibling mutations (`UserID === contextUser.ID`). A **Closed**
+     *    session is accepted: "save my board" legitimately arrives as/after the call ends.
+     * 2. Size cap — `contentJson` beyond {@link MAX_CHANNEL_STATE_CHARS} is a structured failure.
+     * 3. Resolve the {@link WHITEBOARD_ARTIFACT_TYPE_NAME} artifact type by name; when the seed is
+     *    absent/disabled in this deployment, return a structured failure (never throw).
+     * 4. Create the `MJ: Artifacts` header (user-owned, Visibility `Always`) + its
+     *    `MJ: Artifact Versions` v1 row carrying `contentJson`.
+     * 5. Best-effort extras that never fail the save:
+     *    - when the session has a conversation AND a `Conversation Detail` stamped with this
+     *      session id exists (the transcript relay stamps `AgentSessionID`), link the version into
+     *      history via a `MJ: Conversation Detail Artifacts` junction row (Direction `Output`);
+     *    - stamp `LastActiveAt` on the session-channel row when one exists.
+     *
+     * @returns A structured {@link SaveSessionChannelArtifactResult} — graceful failures (missing
+     *   type seed, oversized content, save failure) come back as `Success: false`, while
+     *   authn/ownership violations throw like the sibling mutations.
+     */
+    SaveSessionChannelArtifact(agentSessionId: string, channelName: string, name: string, contentJson: string, { userPayload, providers }: AppContext): Promise<SaveSessionChannelArtifactResult>;
+    /** Resolve the request user + read-write provider, throwing a clear error if unauthenticated. */
+    private requireUserAndProvider;
+    /**
+     * Authorization gate for {@link RealtimeClientSessionResolver.StartRealtimeClientSession}: the
+     * caller must be able to run the **target** agent. Denial throws (no session is created).
+     */
+    private assertCanRunTarget;
+    /**
+     * Resolves the AUTHORITATIVE target agent id under the co-agent's PAIRING CONSTRAINTS
+     * (`MJ: AI Agent Co Agents`, ordered by `Sequence`):
+     *
+     * - **Zero pairing rows (universal co-agent)** — today's behavior untouched: the runtime
+     *   `targetAgentId` is required (clear error when absent) and used as-is. Pairings are NEVER
+     *   mandated; zero-config deployments keep working with zero metadata.
+     * - **Rows + runtime target** — the supplied target must be IN the paired list; a target
+     *   outside the list is a clear structured error (the UX builds its picker from the same rows).
+     * - **Rows + no runtime target** — the `IsDefault` row stands in; when no default row exists,
+     *   a clear error asks for an explicit target.
+     *
+     * Pairing rows are a TARGETING constraint layered on top of — never a replacement for — the
+     * `CanRun` security gate, which the caller applies to the resolved target id immediately
+     * after. A failed/erroring pairing query therefore degrades to the universal behavior
+     * (logged), it never breaks session starts.
+     *
+     * @param coAgentID The resolved co-agent id.
+     * @param requestedTargetId The runtime `targetAgentId` argument, when supplied.
+     * @returns The effective target agent id (canonical casing from the pairing row when matched).
+     */
+    private resolveConstrainedTargetAgentID;
+    /**
+     * Loads the co-agent's pairing rows from {@link AIEngineBase}'s cached
+     * `MJ: AI Agent Co Agents` metadata (provider-scoped engine instance, lazy `Config`),
+     * ordered by `Sequence`. Only **Active** rows of relationship **Type `'CoAgent'`** with a
+     * SPECIFIC agent target participate — type-level rows (`TargetAgentTypeID`) express the
+     * type-default in the resolution chain, not a target restriction, and reserved relationship
+     * types are ignored until their features ship. Tolerant — a failed cache load logs and
+     * returns `[]` (degrading to the universal behavior; pairing is a targeting constraint,
+     * `CanRun` remains the security gate), never throws.
+     */
+    private loadPairingRows;
+    /**
+     * The provider-scoped {@link AIEngineBase} instance for this request's connection, lazily
+     * configured (`Config(false, ...)` is a no-op when the cache is already loaded). Pairing rows
+     * and channel definitions are small metadata tables the engine caches — reading them here
+     * replaces per-call RunViews.
+     */
+    private configuredAIEngineBase;
+    /**
+     * The RUNTIME-OVERRIDE AUTHORIZATION GATE: `configOverridesJson` and a DEVIATING explicit
+     * `preferredModelId` both require the `Realtime: Advanced Session Controls` authorization
+     * (evaluated hierarchy-aware over the caller's roles); a deviating model is additionally
+     * subject to the effective `realtime.allowUserModelOverride` policy (which blocks even
+     * authorized callers when `false`). Denial THROWS a structured reason — never a silent
+     * ignore. Plain starts (no overrides, no explicit model) pass through untouched; an explicit
+     * model EQUAL to the co-agent's metadata-configured preference is not a deviation.
+     *
+     * Judgment calls baked in (per the approved product rules): co-agent selection (`coAgentId`)
+     * and target selection within a pairing list / for a universal co-agent are NORMAL user flow
+     * — they stay behind the existing `CanRun` gate only and are not touched here.
+     */
+    private assertRuntimeOverridesAuthorized;
+    /**
+     * The co-agent's BASELINE effective configuration — type `DefaultConfiguration` ← agent
+     * `TypeConfiguration`, WITHOUT the runtime layer (this feeds the gate that decides whether
+     * the runtime layer is even allowed). Tolerant of an unloaded metadata cache.
+     */
+    private resolveBaselineEffectiveConfig;
+    /**
+     * Resolves the baseline config's `realtime.modelPreference` (Name or ID) to an
+     * `MJ: AI Models.ID`, so a `preferredModelId` equal to it is recognized as a NON-deviation.
+     * When the preference matches no cached model (or the cache is unavailable), the RAW
+     * preference string is returned — an ID-style preference then still compares equal to the
+     * matching `preferredModelId` (case-insensitive), while a name-style preference simply won't
+     * match an id (and the gate treats the request as a deviation — the fail-safe direction).
+     * `null` only when no preference is configured at all.
+     */
+    private resolveMetadataPreferredModelID;
+    /**
+     * Hierarchy-aware check for the `Realtime: Advanced Session Controls` authorization against
+     * the request provider's cached Authorizations + the caller's roles. FAIL-CLOSED: an absent
+     * authorization row (un-synced seed) or an evaluation error denies — runtime overrides are a
+     * privileged path, and unauthorized callers still get a fully working session without them.
+     */
+    private userHasAdvancedSessionControls;
+    /**
+     * Resolves the co-agent (the Realtime-type agent that voices the target agent) for a new
+     * client-direct session via the metadata-driven **CO-AGENT RESOLUTION CHAIN** — first match
+     * wins, evaluated in precedence order:
+     *
+     * 1. **Runtime parameter** — the mutation's explicit `coAgentId`. A per-call override; an
+     *    invalid candidate (unknown, not Active, or not of the Realtime agent type) **throws**
+     *    (fail loud — the caller asked for something specific, mirroring `preferredModelId`).
+     * 2. **Per-agent persona** — the target agent's `AIAgent.DefaultCoAgentID`. An invalid
+     *    reference logs a warning and **falls through** to the next step (stale metadata should
+     *    degrade gracefully, never break calls).
+     * 3. **Per-type default** — an Active `AIAgentCoAgent` row of Type `'CoAgent'` whose
+     *    `TargetAgentTypeID` is the target agent's type and `IsDefault = 1` (lowest `Sequence`
+     *    wins a tie). Same tolerant warn-and-fall-through semantics as step 2.
+     * 4. **Global default** — the seeded {@link REALTIME_CO_AGENT_NAME} agent, looked up by name
+     *    (with a deprecated fallback to {@link LEGACY_REALTIME_CO_AGENT_NAME}). Throws when absent
+     *    entirely (the realtime feature is unconfigured in this deployment).
+     *
+     * Every candidate from steps 1–3 is validated by {@link findValidCoAgent}: it must exist in
+     * {@link AIEngine}'s cached agents, have Status `Active`, and be of the
+     * {@link REALTIME_AGENT_TYPE_NAME} agent type. Step 4 keeps its original name-lookup contract.
+     *
+     * @param targetAgentId The agent the co-agent will voice on behalf of (drives steps 2–3).
+     * @param explicitCoAgentId The runtime `coAgentId` mutation argument, when supplied (step 1).
+     * @returns The resolved co-agent's id (canonical casing from the metadata cache).
+     */
+    private resolveCoAgentID;
+    /**
+     * Chain step 3 lookup: the TYPE-LEVEL default co-agent for an agent type — the Active
+     * `AIAgentCoAgent` row of Type `'CoAgent'` whose `TargetAgentTypeID` matches, with
+     * `IsDefault = 1` preferred and the lowest `Sequence` breaking ties (so a deployment can
+     * stage multiple type-level candidates deterministically). Reads {@link AIEngineBase}'s
+     * cached rows — no RunView. Tolerant: a failed cache read logs and returns `undefined`
+     * (the chain falls through to the global default).
+     */
+    private findTypeDefaultCoAgentID;
+    /**
+     * Validates one metadata-level co-agent default (chain steps 2/3). Returns the resolved
+     * co-agent id when the reference is valid; logs a warning and returns `null` (caller falls
+     * through to the next chain step) when the reference is set but invalid — metadata drift must
+     * degrade, not break live calls. A `null`/absent reference returns `null` silently.
+     */
+    private resolveMetadataDefault;
+    /**
+     * Validates a co-agent candidate against {@link AIEngine}'s cached metadata. A valid co-agent
+     * must (a) exist, (b) have Status `Active`, and (c) be of the {@link REALTIME_AGENT_TYPE_NAME}
+     * agent type. Returns the cached agent on success, or a human-readable `problem` on failure —
+     * the CALLER decides whether that's fatal (explicit runtime param) or tolerated (metadata default).
+     */
+    private findValidCoAgent;
+    /**
+     * Resolves the seeded Realtime Co-Agent's id from {@link AIEngine}'s cached agents — the GLOBAL
+     * DEFAULT (step 4) of the co-agent resolution chain. The engine is already configured by
+     * {@link resolveCoAgentID}. Looks up the current {@link REALTIME_CO_AGENT_NAME} first, then
+     * falls back to the DEPRECATED {@link LEGACY_REALTIME_CO_AGENT_NAME} (pre-rename seed) with a
+     * deprecation log so un-resynced deployments keep working. Throws a clear error when neither
+     * name is present in metadata.
+     */
+    private resolveGlobalCoAgentID;
+    /** Case/whitespace-insensitive agent lookup by Name in {@link AIEngine}'s cached agents. */
+    private findAgentByName;
+    /**
+     * Mints the client session config for a just-created session. On failure, closes the session so
+     * no half-open record leaks, then throws the service's error message.
+     *
+     * @param preferredModelId Optional explicit realtime model choice — threaded to the service,
+     *   which FAILS (no silent fallback) when the chosen model cannot be satisfied.
+     * @param priorTranscript Optional capped, role-tagged transcript of the PRIOR session chain
+     *   (from {@link loadPriorTranscript}) — the service frames it into the system prompt so a
+     *   resumed session remembers the previous leg(s).
+     */
+    private prepareClientSessionOrClose;
+    /**
+     * Writes the co-agent observability run ids into the session's `Config_` alongside the
+     * authoritative `targetAgentID`, then saves the session. These ids are read back on close to
+     * finalize the runs (and on relay to nest delegated runs). Best-effort: a save failure is logged,
+     * not thrown — the voice session still proceeds, it just won't carry the run ids.
+     */
+    private persistObservabilityRunIDs;
+    /**
+     * Loads a session, enforcing inbound ownership (`UserID === contextUser.ID`) and that it is not
+     * `Closed`. Throws on any violation. Returns the loaded session for the caller to read from.
+     */
+    private loadOwnedActiveSession;
+    /**
+     * Loads a session and enforces inbound ownership (`UserID === contextUser.ID`) WITHOUT
+     * rejecting `Closed` sessions — {@link SaveSessionChannelState}'s final on-end flush
+     * legitimately arrives after the session closed. Throws when not found / not owned.
+     */
+    private loadOwnedSession;
+    /**
+     * Resolves an ACTIVE channel definition (`MJ: AI Agent Channels`) by name from
+     * {@link AIEngineBase}'s cached `AgentChannels` (provider-scoped engine instance, lazy
+     * `Config` — no per-call RunView; name matching is trim + case-insensitive, parity with the
+     * previous SQL-collation lookup). Returns its id, or `null` (logged) when no active
+     * definition exists — the channel seed is deployed separately, so its absence is tolerated,
+     * never thrown.
+     */
+    private resolveChannelID;
+    /**
+     * Upserts the session-channel row for `(agentSessionID, channelID)`: creates it with Status
+     * `Connected` when missing, stores `stateJson` in `Config`, and stamps `LastActiveAt`.
+     * Returns the boolean save result (logged on failure).
+     */
+    private upsertSessionChannelState;
+    /**
+     * Loads the PRIOR session's persisted channel states and serializes them as a JSON object
+     * string keyed by channel NAME (the session-channel view denormalizes the channel name as the
+     * `Channel` virtual field). Strictly best-effort — every failure path logs and returns `null`,
+     * a session start NEVER fails because of restore:
+     *  - no `lastSessionId` → `null` (silently — restore simply wasn't requested);
+     *  - prior session missing OR owned by a different user → `null` (logged — never leak another
+     *    user's channel state);
+     *  - rows with an empty `Config` are skipped;
+     *  - an individual state larger than {@link MAX_CHANNEL_STATE_CHARS} is dropped (logged), and
+     *    states that would push the accumulated payload past that same cap are dropped too (logged)
+     *    — the surviving states still restore;
+     *  - no surviving states → `null`.
+     */
+    private loadPriorChannelStatesJson;
+    /**
+     * Loads the PRIOR session chain's transcript for model-context hydration: when a new session
+     * carries `lastSessionId`, the chain's persisted, session-stamped `Conversation Details` are
+     * folded into capped, role-tagged lines (`User: …` / `Assistant: …`) the prepare service
+     * frames into the system prompt — so the model REMEMBERS the previous live leg(s).
+     *
+     * Chain walk + caps:
+     *  - follows `LastSessionID` BACKWARDS from `lastSessionId`, at most
+     *    {@link MAX_PRIOR_TRANSCRIPT_LEGS} legs, with a visited-set cycle guard (A→B→A stops);
+     *  - EVERY leg is ownership-checked like the channel-state restore — the FIRST leg failing
+     *    the check aborts hydration entirely (first leg) or ends the walk (deeper legs), so
+     *    another user's transcript can never leak;
+     *  - one details query covers all collected legs, chronological;
+     *  - hidden/error/empty rows are skipped, then the NEWEST {@link MAX_PRIOR_TRANSCRIPT_TURNS}
+     *    turns are kept and the total is capped at {@link MAX_PRIOR_TRANSCRIPT_CHARS} chars
+     *    (oldest dropped first).
+     *
+     * Strictly best-effort: every failure path logs and returns `undefined` — hydration NEVER
+     * blocks a session start.
+     */
+    private loadPriorTranscript;
+    /**
+     * Walks the prior-session chain backwards from `lastSessionId`, returning the OWNED leg ids
+     * (newest first). The first leg must exist and be owned by the caller, else `[]` (logged);
+     * deeper-leg problems (missing, unowned, cycle) just end the walk.
+     */
+    private collectOwnedPriorLegIDs;
+    /**
+     * Loads the chain legs' visible transcript turns (session-stamped `Conversation Details`,
+     * `Role` User/AI, not hidden, non-empty) in ONE chronological query across all legs.
+     */
+    private loadChainTranscriptTurns;
+    /**
+     * Maps visible turns to role-tagged lines and applies the hydration caps: the NEWEST
+     * {@link MAX_PRIOR_TRANSCRIPT_TURNS} turns, then a total budget of
+     * {@link MAX_PRIOR_TRANSCRIPT_CHARS} chars — oldest lines dropped first in both passes,
+     * so the model always keeps the freshest context.
+     */
+    private capTranscriptLines;
+    /**
+     * Folds prior session-channel rows into a `{ channelName: stateJson }` map, skipping empty
+     * states and enforcing the {@link MAX_CHANNEL_STATE_CHARS} cap both per-state and on the
+     * accumulated total (oversized states are dropped with a log note; the rest survive).
+     */
+    private collectChannelStates;
+    /**
+     * Resolves the ENABLED {@link WHITEBOARD_ARTIFACT_TYPE_NAME} artifact type's id. Returns `null`
+     * (logged) when the type seed is absent or disabled — the artifact-type seed is deployed
+     * separately, so its absence is a graceful structured failure, never a throw.
+     */
+    private resolveWhiteboardArtifactTypeID;
+    /**
+     * Creates the user-owned artifact header + its v1 version for a channel-state save, then runs
+     * the best-effort extras (conversation-history junction + session-channel `LastActiveAt`
+     * stamp). Header/version save failures come back as structured failures; the extras NEVER
+     * fail the save.
+     */
+    private createChannelArtifact;
+    /**
+     * Best-effort: links an artifact version into conversation history the way chat does — via a
+     * `MJ: Conversation Detail Artifacts` junction row (Direction `Output`) against the LATEST
+     * `Conversation Detail` stamped with this session's id (the transcript relay stamps
+     * `AgentSessionID` on every persisted turn). Skips silently (returns `false`) when the session
+     * has no conversation or no stamped detail exists yet; logs (and returns `false`) when the
+     * lookup or junction save fails. Never throws.
+     */
+    private linkVersionToLatestSessionDetail;
+    /**
+     * Best-effort: junction-links the artifacts a DELEGATED target-agent run produced into the
+     * session's conversation history — closing the gap where voice-path artifacts were created
+     * (`RealtimeClientSessionService.createDelegatedRunArtifacts`) but never reached
+     * `MJ: Conversation Detail Artifacts`, leaving chat, session review, and resume carryover
+     * blind to them.
+     *
+     * ANCHOR CHOICE: the junction needs a `Conversation Detail`. We anchor to the MOST RECENT
+     * detail stamped with this session's id (the transcript relay stamps `AgentSessionID` on every
+     * persisted turn) — the turn closest to the tool call that produced the artifact. When NO
+     * stamped detail exists yet (the delegated run finished before the browser relayed any
+     * transcript — the relay is asynchronous), we create a minimal HIDDEN anchor detail
+     * (`Role: 'AI'`, `HiddenToUser: true`, stamped with the session id + conversation + user)
+     * rather than dropping the link: `HiddenToUser` keeps it out of the visible chat thread and
+     * out of review-mode captions (both filter hidden rows), while conversation-level artifact
+     * queries (which scan junctions across ALL details) still surface the artifact. This is the
+     * least-invasive correct anchor — no fake visible message, no orphaned artifact.
+     *
+     * Strictly best-effort: every failure path logs and returns; a relayed tool call NEVER fails
+     * because history linking did.
+     */
+    private linkDelegatedArtifactsToConversation;
+    /**
+     * Finds the LATEST `Conversation Detail` stamped with this session's id (the transcript relay
+     * stamps `AgentSessionID` on every persisted turn). Returns its id, or `null` when none exists.
+     */
+    private findLatestSessionDetailID;
+    /**
+     * Creates the minimal HIDDEN anchor `Conversation Detail` for artifact junction rows when no
+     * session-stamped transcript turn exists yet (see the anchor-choice rationale on
+     * {@link linkDelegatedArtifactsToConversation}). Returns the new detail's id, or `null`
+     * (logged) when the save fails.
+     */
+    private createHiddenSessionAnchorDetail;
+    /**
+     * Saves one `MJ: Conversation Detail Artifacts` junction row (Direction `Output`) linking an
+     * artifact version to a conversation detail. Returns the boolean save result (logged on failure).
+     */
+    private saveDetailArtifactJunction;
+    /**
+     * Best-effort: stamps `LastActiveAt` on the session-channel row for `(session, channelName)`
+     * when one exists — saving an artifact IS channel activity. Missing channel definition or
+     * session-channel row is a silent no-op; failures log and never throw.
+     */
+    private stampSessionChannelLastActive;
+    /**
+     * Tolerantly parses + validates client-declared UI tool definitions (see the SECURITY NOTE on
+     * {@link StartRealtimeClientSession}). Never throws — any rejection logs and returns
+     * `undefined` (the session simply minted without client tools):
+     *  - non-JSON / non-array payloads are rejected wholesale;
+     *  - payloads larger than {@link MAX_CLIENT_TOOLS_JSON_CHARS} are rejected wholesale;
+     *  - more than {@link MAX_CLIENT_TOOLS} declarations are rejected wholesale (a legitimate
+     *    client never sends that many — a flood is a misbehaving caller, not a trim candidate);
+     *  - individual entries failing the shape check (`Name`/`Description` non-empty strings,
+     *    `ParametersSchema` a plain object) are skipped, the rest survive.
+     */
+    private parseClientTools;
+    /** Shape check for one client tool declaration: Name/Description non-empty strings, ParametersSchema a plain object. */
+    private isValidClientTool;
+    /**
+     * Parses the session's persisted config, returning the authoritative `targetAgentID` plus any
+     * observability run ids (`coAgentRunID`/`promptRunID`). Throws when the config is missing/malformed
+     * or carries no target — a relay cannot proceed without a target.
+     */
+    private readSessionConfig;
+    /**
+     * Persists a single transcript turn as a `Conversation Detail` stamped with the session's
+     * conversation, the mapped role, the turn text, the session id, and the owning user.
+     *
+     * @returns The boolean save result (logs `CompleteMessage` on failure).
+     */
+    private persistTranscriptTurn;
+    /**
+     * CORRECTION persistence (the client transcript's `ReplacesPrevious` marker — e.g.
+     * ElevenLabs' post-barge-in `agent_response_correction`): UPDATES the session's most
+     * recently persisted turn of the same role IN PLACE with the corrected text, instead of
+     * appending a near-duplicate. Falls back to a plain insert when no prior turn exists
+     * (the superseded turn may have failed to persist) — a correction is never dropped.
+     */
+    private replacePreviousTranscriptTurn;
+    /**
+     * Maps a transport-level transcript role (`'user'` / `'assistant'`) onto the
+     * `Conversation Detail` entity's `Role` union (`'User'` / `'AI'`). Anything not the user is
+     * treated as the assistant/AI side.
+     */
+    private mapTranscriptRole;
+}
+//# sourceMappingURL=RealtimeClientSessionResolver.d.ts.map