Class RealtimeClientSessionResolver

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.

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.

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).

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 RealtimeClientSessionResolver.StartRealtimeClientSession) and finalized on close; incremental usage telemetry lands on the AIPromptRun via 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.

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.

Persist an interactive channel's current state (e.g. the live whiteboard's board JSON) as a durable, user-owned artifact — distinct from 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 MAX_CHANNEL_STATE_CHARS is a structured failure.
3. Resolve the 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.

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 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.

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 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 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.

Upload a CLIENT-DIRECT session audio recording, store it in MJStorage, link it to the owning AIAgentSession, and stamp the session's recording fields. The browser records locally during the call and uploads the assembled blob (base64) once the session ends.

Hard gates (in order):

1. Ownership — loadOwnedSession enforces UserID === contextUser.ID (throws on violation).
2. Consent — consent !== true is a hard refusal: no audio is ever stored without it.
3. Storage configuration — the session's agent must resolve a recording storage account (the agent's RecordingStorageProviderID, else AttachmentStorageProviderID).

Storage failures (and any unexpected throw) come back as Success: false with a reason — they NEVER throw to the browser, mirroring the shared storeRealtimeRecording contract.

Uploads ONE crash-recovery audio shard (~15s) for an IN-PROGRESS recording into the session's folder (realtime-recordings/<sessionId>/seg-NNNN.<ext>) as a raw storage object. Durability insurance during a live call so a browser/tab death loses at most the last window; the shards are deleted once the canonical consolidated file lands via UploadRealtimeRecording. Ownership- gated; consent was already established at session start. Best-effort — returns false (never throws) on any problem so a failed shard never disrupts the live call.