@memberjunction/realtime-runtime 6.2.0-edge.3 → 6.2.0-edge.5

package/dist/session/realtime-microphone.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @fileoverview The microphone of one realtime session, as a host's device menu shows it: the one the call uses, the
+ * ones the user can move it to (`RealtimeSessionRuntime.SwitchMicrophone`), and why none works once the call lost it.
+ *
+ * The call opens the microphone through the host's camera-and-microphone controller, and the controller reports the
+ * device in use and the devices the browser lists. This module reads the microphone's part of that report. It shows
+ * nothing outside a call and nothing on a host without a controller, which opens the microphone itself
+ * (`IRealtimeMediaHost.AcquireMicrophone`) and so has no list to offer.
+ *
+ * @module @memberjunction/realtime-runtime
+ */
+import type { LocalMediaFailure, LocalMediaState, MediaDevice } from '@memberjunction/ai-realtime-client';
+/** The call's microphone: the one in use, the ones the user can move it to, and why none works once the call lost it. */
+export interface RealtimeMicrophoneState {
+    /**
+     * The microphone in use. Kept while a switch is under way, until the new one is on. Absent outside a call, on a host
+     * without a controller, and when the controller has no microphone open (it stopped, or no device could open).
+     */
+    DeviceID?: string;
+    /**
+     * The microphones the browser lists while the call is connected: what `SwitchMicrophone` can move to. The call has
+     * opened the microphone, so the browser gives their names. Empty outside a call and on a host without a controller.
+     */
+    Devices: readonly MediaDevice[];
+    /**
+     * Why no microphone works: the call lost its microphone (the one in use failed and so did the fallback to the default,
+     * or the last one went away), so the agent hears nothing until the user picks one with `SwitchMicrophone`. Kept while
+     * the picked one opens, and gone once a microphone is on. Absent while the microphone works or is being switched,
+     * outside a call, and on a host without a controller.
+     */
+    Failure?: LocalMediaFailure;
+}
+/** No microphone to show or switch: what a host gets outside a call and on a host without a controller. */
+export declare const REALTIME_MICROPHONE_NONE: RealtimeMicrophoneState;
+/**
+ * The call's microphone as a controller reports it. The device in use is the controller's while its microphone is on.
+ * While the controller is starting a microphone (a switch, a lost device replaced by the default, or a pick after the call
+ * lost its microphone), the call keeps what it shows now: the microphone in use, so a device menu keeps showing it until
+ * the new one is on, or why none works. Failed, there is none, and the failure says why. Stopped, there is none.
+ *
+ * @param media The controller's state.
+ * @param current What the call shows now.
+ */
+export declare function ReadMicrophoneState(media: LocalMediaState, current?: RealtimeMicrophoneState): RealtimeMicrophoneState;
+/**
+ * Whether two states name the same microphone in use, list the same microphones (by id and name, in the same order) and
+ * give the same failure.
+ */
+export declare function SameMicrophoneState(a: RealtimeMicrophoneState, b: RealtimeMicrophoneState): boolean;
+//# sourceMappingURL=realtime-microphone.d.ts.map

package/dist/session/realtime-microphone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-microphone.d.ts","sourceRoot":"","sources":["../../src/session/realtime-microphone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oCAAoC,CAAC;AAE1G,yHAAyH;AACzH,MAAM,WAAW,uBAAuB;IACpC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IAChC;;;;;OAKG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,2GAA2G;AAC3G,eAAO,MAAM,wBAAwB,EAAE,uBAAuE,CAAC;AAE/G;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,eAAe,EAAE,OAAO,GAAE,uBAAkD,GAAG,uBAAuB,CAiBhJ;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,uBAAuB,EAAE,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAOnG"}

package/dist/session/realtime-microphone.js

@@ -0,0 +1,51 @@
+/**
+ * @fileoverview The microphone of one realtime session, as a host's device menu shows it: the one the call uses, the
+ * ones the user can move it to (`RealtimeSessionRuntime.SwitchMicrophone`), and why none works once the call lost it.
+ *
+ * The call opens the microphone through the host's camera-and-microphone controller, and the controller reports the
+ * device in use and the devices the browser lists. This module reads the microphone's part of that report. It shows
+ * nothing outside a call and nothing on a host without a controller, which opens the microphone itself
+ * (`IRealtimeMediaHost.AcquireMicrophone`) and so has no list to offer.
+ *
+ * @module @memberjunction/realtime-runtime
+ */
+/** No microphone to show or switch: what a host gets outside a call and on a host without a controller. */
+export const REALTIME_MICROPHONE_NONE = Object.freeze({ Devices: Object.freeze([]) });
+/**
+ * The call's microphone as a controller reports it. The device in use is the controller's while its microphone is on.
+ * While the controller is starting a microphone (a switch, a lost device replaced by the default, or a pick after the call
+ * lost its microphone), the call keeps what it shows now: the microphone in use, so a device menu keeps showing it until
+ * the new one is on, or why none works. Failed, there is none, and the failure says why. Stopped, there is none.
+ *
+ * @param media The controller's state.
+ * @param current What the call shows now.
+ */
+export function ReadMicrophoneState(media, current = REALTIME_MICROPHONE_NONE) {
+    const microphone = media.Microphone;
+    const devices = media.Devices.filter((d) => d.Kind === 'microphone');
+    switch (microphone.Status) {
+        case 'on':
+            return { ...(microphone.DeviceID ? { DeviceID: microphone.DeviceID } : {}), Devices: devices };
+        case 'starting':
+            return {
+                ...(current.DeviceID ? { DeviceID: current.DeviceID } : {}),
+                ...(current.Failure ? { Failure: current.Failure } : {}),
+                Devices: devices,
+            };
+        case 'failed':
+            return { Failure: microphone.Failure ?? 'error', Devices: devices };
+        default:
+            return { Devices: devices };
+    }
+}
+/**
+ * Whether two states name the same microphone in use, list the same microphones (by id and name, in the same order) and
+ * give the same failure.
+ */
+export function SameMicrophoneState(a, b) {
+    return (a.DeviceID === b.DeviceID &&
+        a.Failure === b.Failure &&
+        a.Devices.length === b.Devices.length &&
+        a.Devices.every((d, i) => d.DeviceID === b.Devices[i].DeviceID && d.Label === b.Devices[i].Label));
+}
+//# sourceMappingURL=realtime-microphone.js.map

package/dist/session/realtime-microphone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-microphone.js","sourceRoot":"","sources":["../../src/session/realtime-microphone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAyBH,2GAA2G;AAC3G,MAAM,CAAC,MAAM,wBAAwB,GAA4B,MAAM,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;AAE/G;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAsB,EAAE,UAAmC,wBAAwB;IACnH,MAAM,UAAU,GAAG,KAAK,CAAC,UAAU,CAAC;IACpC,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,YAAY,CAAC,CAAC;IACrE,QAAQ,UAAU,CAAC,MAAM,EAAE,CAAC;QACxB,KAAK,IAAI;YACL,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QACnG,KAAK,UAAU;YACX,OAAO;gBACH,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC3D,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxD,OAAO,EAAE,OAAO;aACnB,CAAC;QACN,KAAK,QAAQ;YACT,OAAO,EAAE,OAAO,EAAE,UAAU,CAAC,OAAO,IAAI,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;QACxE;YACI,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IACpC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,CAA0B,EAAE,CAA0B;IACtF,OAAO,CACH,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,QAAQ;QACzB,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO;QACvB,CAAC,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,CAAC,OAAO,CAAC,MAAM;QACrC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CACpG,CAAC;AACN,CAAC"}

package/dist/session/session-event-hub.d.ts

@@ -0,0 +1,72 @@
+import type { Observable } from 'rxjs';
+import type { RealtimeSessionEvent, UnknownRealtimeSessionEvent } from '@memberjunction/ai-core-plus';
+/** An event a session delivers: a known, typed one, or an app-defined one the runtime does not interpret. */
+export type RealtimeSessionStreamEvent = RealtimeSessionEvent | UnknownRealtimeSessionEvent;
+/** The slice of a verification status read the hub needs to recover a missed `identity.verified`. */
+export interface RealtimeSessionVerificationSnapshot {
+    VerificationState: 'unverified' | 'pending' | 'verified';
+    VerifiedEmail?: string;
+    VerifiedAt?: string;
+    MaxSessionDeadlineIso?: string;
+}
+/**
+ * Where session events come from — the transport seam. `GraphQLRealtimeSessionClient`
+ * (`@memberjunction/graphql-dataprovider`) satisfies this structurally; a host on another transport
+ * supplies its own.
+ */
+export interface IRealtimeSessionEventSource {
+    /** Opens the session's event stream. It completes when the transport recycles (e.g. a token refresh). */
+    SubscribeToSessionEvents(agentSessionId: string): Observable<RealtimeSessionStreamEvent>;
+    /** Reads the session's verification state once — the durable backstop for an event missed while away. Never throws. */
+    GetVerificationStatus(agentSessionId: string): Promise<RealtimeSessionVerificationSnapshot>;
+}
+/** Tuning for {@link RealtimeSessionEventHub}'s reconnect loop. */
+export interface RealtimeSessionEventHubOptions {
+    /** Consecutive failed/short-lived subscriptions tolerated before the hub gives up. Default 6. */
+    MaxReconnectAttempts?: number;
+    /** First reconnect delay; doubles per consecutive attempt up to {@link MaxBackoffMs}. Default 1000. */
+    BaseBackoffMs?: number;
+    /** Ceiling of the reconnect delay. Default 15000. */
+    MaxBackoffMs?: number;
+    /** A subscription that lived at least this long counts as healthy and resets the attempt counter. Default 30000. */
+    StableAfterMs?: number;
+}
+/**
+ * Keeps one session's event stream open for the session's life and delivers every event to a sink.
+ *
+ * The stream is a long-lived subscription that ends when the transport recycles its connection (token
+ * refresh, network blip) — and delivery has no replay, so an event published during the gap is gone.
+ * The hub therefore, on every re-subscribe: opens the new subscription FIRST (so nothing published
+ * from now on is missed), THEN reads the verification status once, and if the person verified while the
+ * hub was away, delivers the `identity.verified` event it missed (marked `Recovered`).
+ *
+ * Reconnects are capped: a stream that keeps failing is given up on (once, loudly) rather than retried
+ * forever; a stream that stayed up long enough counts as healthy and resets the cap.
+ *
+ * Framework-agnostic and clock-driven by `setTimeout`, so tests drive it with fake timers.
+ */
+export declare class RealtimeSessionEventHub {
+    private readonly source;
+    private readonly deliver;
+    private readonly options;
+    private sessionId;
+    private subscription;
+    private reconnectTimer;
+    private attempts;
+    private verifiedDelivered;
+    /** Bumped by every Start/Stop so a late callback from a previous run can tell it is stale. */
+    private generation;
+    constructor(source: IRealtimeSessionEventSource, deliver: (event: RealtimeSessionStreamEvent) => void, options?: RealtimeSessionEventHubOptions);
+    /** Whether the hub currently has (or is about to re-open) a subscription. */
+    get IsRunning(): boolean;
+    /** Opens the stream for `agentSessionId`. Replaces any run in progress. */
+    Start(agentSessionId: string): void;
+    /** Closes the stream and cancels any pending reconnect. Safe to call when not running. */
+    Stop(): void;
+    private connect;
+    private onEvent;
+    private onStreamEnded;
+    /** Reads the verification status once and delivers the `identity.verified` event the hub missed, if any. */
+    private recoverMissedVerification;
+}
+//# sourceMappingURL=session-event-hub.d.ts.map

package/dist/session/session-event-hub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-event-hub.d.ts","sourceRoot":"","sources":["../../src/session/session-event-hub.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAgB,MAAM,MAAM,CAAC;AACrD,OAAO,KAAK,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,MAAM,8BAA8B,CAAC;AAEtG,6GAA6G;AAC7G,MAAM,MAAM,0BAA0B,GAAG,oBAAoB,GAAG,2BAA2B,CAAC;AAE5F,qGAAqG;AACrG,MAAM,WAAW,mCAAmC;IAClD,iBAAiB,EAAE,YAAY,GAAG,SAAS,GAAG,UAAU,CAAC;IACzD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B;IAC1C,yGAAyG;IACzG,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,UAAU,CAAC,0BAA0B,CAAC,CAAC;IACzF,uHAAuH;IACvH,qBAAqB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,mCAAmC,CAAC,CAAC;CAC7F;AAED,mEAAmE;AACnE,MAAM,WAAW,8BAA8B;IAC7C,iGAAiG;IACjG,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,uGAAuG;IACvG,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,oHAAoH;IACpH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AASD;;;;;;;;;;;;;GAaG;AACH,qBAAa,uBAAuB;IAWhC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAX1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA2C;IACnE,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,iBAAiB,CAAS;IAClC,8FAA8F;IAC9F,OAAO,CAAC,UAAU,CAAK;gBAGJ,MAAM,EAAE,2BAA2B,EACnC,OAAO,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,EACrE,OAAO,GAAE,8BAAmC;IAK9C,6EAA6E;IAC7E,IAAW,SAAS,IAAI,OAAO,CAE9B;IAED,2EAA2E;IACpE,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI;IAQ1C,0FAA0F;IACnF,IAAI,IAAI,IAAI;IAWnB,OAAO,CAAC,OAAO;IA2Bf,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,aAAa;IA0BrB,4GAA4G;YAC9F,yBAAyB;CAgCxC"}

package/dist/session/session-event-hub.js

@@ -0,0 +1,151 @@
+const DEFAULTS = {
+    MaxReconnectAttempts: 6,
+    BaseBackoffMs: 1000,
+    MaxBackoffMs: 15_000,
+    StableAfterMs: 30_000
+};
+/**
+ * Keeps one session's event stream open for the session's life and delivers every event to a sink.
+ *
+ * The stream is a long-lived subscription that ends when the transport recycles its connection (token
+ * refresh, network blip) — and delivery has no replay, so an event published during the gap is gone.
+ * The hub therefore, on every re-subscribe: opens the new subscription FIRST (so nothing published
+ * from now on is missed), THEN reads the verification status once, and if the person verified while the
+ * hub was away, delivers the `identity.verified` event it missed (marked `Recovered`).
+ *
+ * Reconnects are capped: a stream that keeps failing is given up on (once, loudly) rather than retried
+ * forever; a stream that stayed up long enough counts as healthy and resets the cap.
+ *
+ * Framework-agnostic and clock-driven by `setTimeout`, so tests drive it with fake timers.
+ */
+export class RealtimeSessionEventHub {
+    constructor(source, deliver, options = {}) {
+        this.source = source;
+        this.deliver = deliver;
+        this.sessionId = null;
+        this.subscription = null;
+        this.reconnectTimer = null;
+        this.attempts = 0;
+        this.verifiedDelivered = false;
+        /** Bumped by every Start/Stop so a late callback from a previous run can tell it is stale. */
+        this.generation = 0;
+        this.options = { ...DEFAULTS, ...options };
+    }
+    /** Whether the hub currently has (or is about to re-open) a subscription. */
+    get IsRunning() {
+        return this.sessionId !== null;
+    }
+    /** Opens the stream for `agentSessionId`. Replaces any run in progress. */
+    Start(agentSessionId) {
+        this.Stop();
+        this.sessionId = agentSessionId;
+        this.attempts = 0;
+        this.verifiedDelivered = false;
+        this.connect(false);
+    }
+    /** Closes the stream and cancels any pending reconnect. Safe to call when not running. */
+    Stop() {
+        this.generation++;
+        this.sessionId = null;
+        if (this.reconnectTimer !== null) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.subscription?.unsubscribe();
+        this.subscription = null;
+    }
+    connect(isReconnect) {
+        const sessionId = this.sessionId;
+        if (sessionId === null) {
+            return;
+        }
+        const generation = this.generation;
+        const openedAt = Date.now();
+        this.subscription?.unsubscribe();
+        try {
+            this.subscription = this.source.SubscribeToSessionEvents(sessionId).subscribe({
+                next: (event) => this.onEvent(generation, event),
+                error: (error) => {
+                    console.warn('[RealtimeSession] The session event stream failed:', error);
+                    this.onStreamEnded(generation, openedAt);
+                },
+                complete: () => this.onStreamEnded(generation, openedAt)
+            });
+        }
+        catch (error) {
+            console.warn('[RealtimeSession] Could not open the session event stream:', error);
+            this.onStreamEnded(generation, openedAt);
+            return;
+        }
+        if (isReconnect) {
+            void this.recoverMissedVerification(generation, sessionId);
+        }
+    }
+    onEvent(generation, event) {
+        if (generation !== this.generation) {
+            return;
+        }
+        if (event.Type === 'identity.verified') {
+            this.verifiedDelivered = true;
+        }
+        this.deliver(event);
+    }
+    onStreamEnded(generation, openedAt) {
+        if (generation !== this.generation || this.sessionId === null) {
+            return;
+        }
+        if (Date.now() - openedAt >= this.options.StableAfterMs) {
+            this.attempts = 0;
+        }
+        this.attempts++;
+        if (this.attempts > this.options.MaxReconnectAttempts) {
+            console.error(`[RealtimeSession] The session event stream for ${this.sessionId} kept ending; giving up after ${this.options.MaxReconnectAttempts} attempts. ` +
+                'Session events (such as identity verification) will not arrive until the next session.');
+            this.sessionId = null;
+            this.subscription = null;
+            return;
+        }
+        const delay = Math.min(this.options.BaseBackoffMs * 2 ** (this.attempts - 1), this.options.MaxBackoffMs);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            if (generation === this.generation) {
+                this.connect(true);
+            }
+        }, delay);
+    }
+    /** Reads the verification status once and delivers the `identity.verified` event the hub missed, if any. */
+    async recoverMissedVerification(generation, sessionId) {
+        if (this.verifiedDelivered) {
+            return;
+        }
+        let status;
+        try {
+            status = await this.source.GetVerificationStatus(sessionId);
+        }
+        catch (error) {
+            console.warn('[RealtimeSession] Could not read the verification status after reconnecting:', error);
+            return;
+        }
+        if (generation !== this.generation || this.verifiedDelivered) {
+            return; // stopped, restarted, or the live event arrived while the status was in flight
+        }
+        if (status.VerificationState !== 'verified' || !status.VerifiedEmail || !status.VerifiedAt) {
+            return;
+        }
+        this.verifiedDelivered = true;
+        this.deliver({
+            Type: 'identity.verified',
+            AgentSessionID: sessionId,
+            OccurredAt: status.VerifiedAt,
+            Payload: {
+                VerifiedEmail: status.VerifiedEmail,
+                VerifiedName: '',
+                VerifiedAt: status.VerifiedAt,
+                Method: 'link',
+                ...(status.MaxSessionDeadlineIso ? { MaxSessionDeadlineIso: status.MaxSessionDeadlineIso } : {}),
+                Recovered: true
+            }
+        });
+    }
+}
+//# sourceMappingURL=session-event-hub.js.map

package/dist/session/session-event-hub.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-event-hub.js","sourceRoot":"","sources":["../../src/session/session-event-hub.ts"],"names":[],"mappings":"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"}

package/dist/session/session-launcher.d.ts

@@ -0,0 +1,128 @@
+import type { IMetadataProvider } from '@memberjunction/core';
+import { type RealtimeToolDefinition } from '@memberjunction/ai';
+import type { AppContextSnapshot } from '@memberjunction/ai-core-plus';
+import type { StartRealtimeClientSessionResult } from './RealtimeSessionRuntime.js';
+/**
+ * Everything the runtime knows when it needs a session minted — the inputs of the stock
+ * `StartRealtimeClientSession` mutation, as typed values rather than a GraphQL variable bag.
+ *
+ * A launcher may use all, some or none of it: the default sends it to the stock mutation; a
+ * host-specific launcher can map it onto its own mint (a deployment-specific mutation, a REST
+ * endpoint, a guest-session exchange) so long as it returns a {@link StartRealtimeClientSessionResult}.
+ */
+export interface RealtimeSessionLaunchRequest {
+    /** The agent the session fronts. */
+    TargetAgentId: string;
+    /** The conversation the session belongs to, when it continues one. */
+    ConversationId: string | null;
+    /** A prior session whose saved channel state this one resumes. */
+    LastSessionId: string | null;
+    /** A realtime model the user picked, when the host exposes a model picker. */
+    PreferredModelId: string | null;
+    /**
+     * Client-executed tools to declare to the model at mint: the host's own plus the native tools of the
+     * channels mounted with the session. A launcher that mints through its own endpoint must pass them on,
+     * or the model never learns it can call them.
+     */
+    ClientTools: readonly RealtimeToolDefinition[];
+    /** The co-agent override, or `null` to let server metadata choose. */
+    CoAgentId: string | null;
+    /** Session-config overrides (authorization-gated server side), as JSON. */
+    ConfigOverridesJson: string | null;
+    /** Whether the user consented to recording this session. */
+    RecordingConsent: boolean;
+    /** When the recording started (ISO), or `null` when the session is not being recorded. */
+    RecordingStartedAt: string | null;
+    /** A per-session media-kit collection override. */
+    MediaCollectionId: string | null;
+    /** The application the session runs in. */
+    ApplicationId: string | null;
+    /** The live app-context snapshot to inject into the companion prompt. */
+    AppContext: AppContextSnapshot | null;
+    /**
+     * The channels this host can mount (JSON), which the server scopes against the agent's and the app's
+     * configuration and answers with the resolved policy. `null` when the host brings none.
+     */
+    ChannelCandidatesJson: string | null;
+    /** The fork (`MJ: Conversation Branches.ID`) the session starts on; `null` is Main. */
+    ConversationBranchId: string | null;
+    /**
+     * Whether this host can show the agent's video: one of its channels shows it (the Avatar channel). `false` for a host
+     * with none (the embeddable widget, the mobile app): the server then asks the model for no avatar, so a video model is
+     * not chosen for a face nobody would see, and says why (`host`). A launcher that mints through its own endpoint should
+     * pass a `false` on. Absent: not stated, and the server assumes the host may show it.
+     */
+    ShowsAgentVideo?: boolean;
+}
+/** What the runtime hands a launcher besides the request: the provider the session runs on. */
+export interface RealtimeSessionLaunchContext {
+    /**
+     * The MJ provider this session is authenticated on. The default launcher mints through it; a custom
+     * launcher that talks to MJ should do the same so the call rides the session's credential.
+     */
+    Provider: IMetadataProvider;
+}
+/**
+ * How a realtime session gets MINTED — the seam between "a host wants a session" and "the server has
+ * created one and handed back a token".
+ *
+ * The runtime owns everything either side of it (channel scoping, driver resolution, connecting,
+ * transcripts, teardown). A launcher owns only the exchange. That is what lets an app change how a
+ * session is minted — a guest-session exchange, a deployment-specific mutation that carries server-side
+ * context the stock one cannot — without proxying the runtime's provider or re-implementing the run
+ * half. Install one with {@link RealtimeSessionRuntime.Launcher}.
+ *
+ * A launcher must either resolve a usable result (one carrying an ephemeral token, or a relay session's relay URL) or
+ * throw; the runtime turns a throw into a failed start with the error on `LastStartError`.
+ */
+export interface IRealtimeSessionLauncher {
+    /**
+     * Mints one session.
+     *
+     * @param request The inputs the runtime resolved for this start.
+     * @param context The provider the session runs on.
+     * @returns The minted session, including `ClientPolicyJson` when the launcher's mint scoped channels,
+     *   `AvatarStatusJson` when the server reports the session's avatar status, and `Transport` and `RelayUrl` for a
+     *   session that runs through MJAPI's realtime relay.
+     */
+    Launch(request: RealtimeSessionLaunchRequest, context: RealtimeSessionLaunchContext): Promise<StartRealtimeClientSessionResult>;
+}
+/**
+ * Whether a minted session carries what its client driver connects with: an ephemeral token, or, for a relay session
+ * (`Transport` `'relay'`), its relay URL.
+ *
+ * @param result The minted session, or nothing.
+ */
+export declare function HasClientCredential(result: Pick<StartRealtimeClientSessionResult, 'EphemeralToken' | 'Transport' | 'RelayUrl'> | null | undefined): boolean;
+/**
+ * The stock launcher: mints through the `StartRealtimeClientSession` GraphQL mutation on the session's
+ * provider. This is what every host gets unless it installs another.
+ *
+ * When the session has channel candidates it asks the server to scope them (`channelCandidatesJson`)
+ * and to return the resolved policy (`ClientPolicyJson`). It also asks for the session's live-avatar status
+ * (`AvatarStatusJson`), which the call reads to say why it shows no avatar, and for how the browser reaches the
+ * provider (`Transport` and `RelayUrl`), which a relay session's client driver connects with. A host that shows no agent
+ * video ({@link RealtimeSessionLaunchRequest.ShowsAgentVideo} `false`) says so (`showsAgentVideo: false`), so the
+ * server asks the model for no avatar. A server that predates an extension rejects it at validation, in which case the
+ * launcher mints without that extension alone (the runtime then resolves the channel scope locally, shows no avatar
+ * notice, treats every session as direct, or leaves the avatar to the browser's audio-only fallback at connect) — a new
+ * client must keep working against an older server, and a failed mint over an optional extension would be the worst way
+ * to find out they differ. Each fallback is remembered per launcher instance so a long-lived runtime asks once.
+ */
+export declare class DefaultRealtimeSessionLauncher implements IRealtimeSessionLauncher {
+    /** The extensions of the mint the server rejected; each is added once and kept. */
+    private readonly serverLacks;
+    Launch(request: RealtimeSessionLaunchRequest, context: RealtimeSessionLaunchContext): Promise<StartRealtimeClientSessionResult>;
+    /** The mutation's variables for one request. */
+    private buildVariables;
+    /**
+     * Runs the mint with every extension this server has not rejected, dropping one at a time when the server rejects it
+     * at validation. Each retry asks for one extension fewer, so the loop ends.
+     */
+    private executeMintMutation;
+    /** Remembers that the server lacks an extension of the mint, and says so once. */
+    private rememberUnsupported;
+    /** The `StartRealtimeClientSession` document, with the extensions asked for. */
+    private buildMintMutation;
+}
+//# sourceMappingURL=session-launcher.d.ts.map

package/dist/session/session-launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-launcher.d.ts","sourceRoot":"","sources":["../../src/session/session-launcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,OAAO,EAAgD,KAAK,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC/G,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,KAAK,EAAE,gCAAgC,EAAE,MAAM,0BAA0B,CAAC;AAEjF;;;;;;;GAOG;AACH,MAAM,WAAW,4BAA4B;IAC3C,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,kEAAkE;IAClE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;OAIG;IACH,WAAW,EAAE,SAAS,sBAAsB,EAAE,CAAC;IAC/C,sEAAsE;IACtE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,2EAA2E;IAC3E,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,4DAA4D;IAC5D,gBAAgB,EAAE,OAAO,CAAC;IAC1B,0FAA0F;IAC1F,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,mDAAmD;IACnD,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,2CAA2C;IAC3C,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,yEAAyE;IACzE,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACtC;;;OAGG;IACH,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,uFAAuF;IACvF,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAED,+FAA+F;AAC/F,MAAM,WAAW,4BAA4B;IAC3C;;;OAGG;IACH,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;;;;;OAQG;IACH,MAAM,CAAC,OAAO,EAAE,4BAA4B,EAAE,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,gCAAgC,CAAC,CAAC;CACjI;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,gCAAgC,EAAE,gBAAgB,GAAG,WAAW,GAAG,UAAU,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAK3J;AAoDD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,8BAA+B,YAAW,wBAAwB;IAC7E,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmC;IAElD,MAAM,CAAC,OAAO,EAAE,4BAA4B,EAAE,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,gCAAgC,CAAC;IAW5I,gDAAgD;IAChD,OAAO,CAAC,cAAc;IAkBtB;;;OAGG;YACW,mBAAmB;IA+BjC,kFAAkF;IAClF,OAAO,CAAC,mBAAmB;IAK3B,gFAAgF;IAChF,OAAO,CAAC,iBAAiB;CA8B1B"}

package/dist/session/session-launcher.js

@@ -0,0 +1,160 @@
+import { ParseRealtimeClientTransport } from '@memberjunction/ai';
+/**
+ * Whether a minted session carries what its client driver connects with: an ephemeral token, or, for a relay session
+ * (`Transport` `'relay'`), its relay URL.
+ *
+ * @param result The minted session, or nothing.
+ */
+export function HasClientCredential(result) {
+    if (!result) {
+        return false;
+    }
+    return !!result.EphemeralToken || (ParseRealtimeClientTransport(result.Transport) === 'relay' && !!result.RelayUrl);
+}
+/** What the launcher says, once, when the server rejects an extension of the mint. */
+const UNSUPPORTED_EXTENSION_WARNINGS = {
+    ChannelScoping: '[RealtimeSession] The server does not support channel scoping — minting without it and resolving channels locally.',
+    AvatarStatus: '[RealtimeSession] The server does not report the avatar status — minting without it; the call shows no avatar notice.',
+    RelayTransport: '[RealtimeSession] The server does not report the session transport — minting without it; every session connects directly.',
+    NoAgentVideo: "[RealtimeSession] The server does not take showsAgentVideo — minting without it; it may ask for an avatar this app can't show (the call stays audio only).",
+};
+/**
+ * The extension a mint failure rejects, when the failure is a GraphQL validation rejection of one the mint asked for —
+ * the signature of a server that predates it ("Unknown argument "channelCandidatesJson"…", "Cannot query field
+ * "ClientPolicyJson"…", "Cannot query field "AvatarStatusJson"…", "Cannot query field "Transport"…", "Unknown argument
+ * "showsAgentVideo"…"). Only that case is recoverable; any other failure is a real mint failure and must surface. A
+ * rejection names one field at a time, so a server that predates several extensions is found out one step at a time.
+ */
+function unsupportedExtension(error, asked) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (asked.NoAgentVideo && message.includes('showsAgentVideo')) {
+        return 'NoAgentVideo';
+    }
+    if (asked.AvatarStatus && message.includes('AvatarStatusJson')) {
+        return 'AvatarStatus';
+    }
+    // The quoted field names, not the bare words: "Transport" alone could be any transport error, and "RelayUrl"
+    // any message that names the field.
+    if (asked.RelayTransport && (message.includes('field "Transport"') || message.includes('field "RelayUrl"'))) {
+        return 'RelayTransport';
+    }
+    if (asked.ChannelScoping && (message.includes('channelCandidatesJson') || message.includes('ClientPolicyJson'))) {
+        return 'ChannelScoping';
+    }
+    return null;
+}
+/**
+ * The stock launcher: mints through the `StartRealtimeClientSession` GraphQL mutation on the session's
+ * provider. This is what every host gets unless it installs another.
+ *
+ * When the session has channel candidates it asks the server to scope them (`channelCandidatesJson`)
+ * and to return the resolved policy (`ClientPolicyJson`). It also asks for the session's live-avatar status
+ * (`AvatarStatusJson`), which the call reads to say why it shows no avatar, and for how the browser reaches the
+ * provider (`Transport` and `RelayUrl`), which a relay session's client driver connects with. A host that shows no agent
+ * video ({@link RealtimeSessionLaunchRequest.ShowsAgentVideo} `false`) says so (`showsAgentVideo: false`), so the
+ * server asks the model for no avatar. A server that predates an extension rejects it at validation, in which case the
+ * launcher mints without that extension alone (the runtime then resolves the channel scope locally, shows no avatar
+ * notice, treats every session as direct, or leaves the avatar to the browser's audio-only fallback at connect) — a new
+ * client must keep working against an older server, and a failed mint over an optional extension would be the worst way
+ * to find out they differ. Each fallback is remembered per launcher instance so a long-lived runtime asks once.
+ */
+export class DefaultRealtimeSessionLauncher {
+    constructor() {
+        /** The extensions of the mint the server rejected; each is added once and kept. */
+        this.serverLacks = new Set();
+    }
+    async Launch(request, context) {
+        // The session's provider is the GraphQL one in every shipped host; this is the same narrowing the runtime applies for its relay mutations.
+        const transport = context.Provider;
+        const result = await this.executeMintMutation(transport, this.buildVariables(request), request.ChannelCandidatesJson, request.ShowsAgentVideo === false);
+        const payload = result?.StartRealtimeClientSession;
+        if (!payload || !HasClientCredential(payload)) {
+            throw new Error('StartRealtimeClientSession returned no ephemeral token (or, for a relay session, no relay URL)');
+        }
+        return payload;
+    }
+    /** The mutation's variables for one request. */
+    buildVariables(request) {
+        return {
+            targetAgentId: request.TargetAgentId,
+            conversationId: request.ConversationId,
+            lastSessionId: request.LastSessionId,
+            preferredModelId: request.PreferredModelId,
+            clientToolsJson: request.ClientTools.length > 0 ? JSON.stringify(request.ClientTools) : null,
+            coAgentId: request.CoAgentId,
+            configOverridesJson: request.ConfigOverridesJson,
+            recordingConsent: request.RecordingConsent,
+            recordingStartedAt: request.RecordingStartedAt,
+            mediaCollectionId: request.MediaCollectionId,
+            applicationId: request.ApplicationId,
+            appContextJson: request.AppContext ? JSON.stringify(request.AppContext) : null,
+            conversationBranchId: request.ConversationBranchId
+        };
+    }
+    /**
+     * Runs the mint with every extension this server has not rejected, dropping one at a time when the server rejects it
+     * at validation. Each retry asks for one extension fewer, so the loop ends.
+     */
+    async executeMintMutation(transport, variables, channelCandidatesJson, noAgentVideo) {
+        let asked = {
+            ChannelScoping: channelCandidatesJson !== null && !this.serverLacks.has('ChannelScoping'),
+            AvatarStatus: !this.serverLacks.has('AvatarStatus'),
+            RelayTransport: !this.serverLacks.has('RelayTransport'),
+            NoAgentVideo: noAgentVideo && !this.serverLacks.has('NoAgentVideo'),
+        };
+        for (;;) {
+            try {
+                const mintVariables = {
+                    ...variables,
+                    ...(asked.ChannelScoping ? { channelCandidatesJson } : {}),
+                    ...(asked.NoAgentVideo ? { showsAgentVideo: false } : {}),
+                };
+                return await transport.ExecuteGQL(this.buildMintMutation(asked), mintVariables);
+            }
+            catch (error) {
+                const unsupported = unsupportedExtension(error, asked);
+                if (!unsupported) {
+                    throw error;
+                }
+                this.rememberUnsupported(unsupported);
+                asked = { ...asked, [unsupported]: false };
+            }
+        }
+    }
+    /** Remembers that the server lacks an extension of the mint, and says so once. */
+    rememberUnsupported(extension) {
+        console.warn(UNSUPPORTED_EXTENSION_WARNINGS[extension]);
+        this.serverLacks.add(extension);
+    }
+    /** The `StartRealtimeClientSession` document, with the extensions asked for. */
+    buildMintMutation(asked) {
+        const extraVariable = (asked.ChannelScoping ? ', $channelCandidatesJson: String' : '') + (asked.NoAgentVideo ? ', $showsAgentVideo: Boolean' : '');
+        const extraArgument = (asked.ChannelScoping ? ', channelCandidatesJson: $channelCandidatesJson' : '') + (asked.NoAgentVideo ? ', showsAgentVideo: $showsAgentVideo' : '');
+        const extraField = [
+            asked.ChannelScoping ? 'ClientPolicyJson' : '',
+            asked.AvatarStatus ? 'AvatarStatusJson' : '',
+            asked.RelayTransport ? 'Transport' : '',
+            asked.RelayTransport ? 'RelayUrl' : '',
+        ]
+            .filter((field) => field.length > 0)
+            .map((field) => `\n          ${field}`)
+            .join('');
+        return `
+      mutation StartRealtimeClientSession($targetAgentId: String!, $conversationId: String, $lastSessionId: String, $preferredModelId: String, $clientToolsJson: String, $coAgentId: String, $configOverridesJson: String, $recordingConsent: Boolean, $recordingStartedAt: String, $mediaCollectionId: String, $applicationId: String, $appContextJson: String, $conversationBranchId: String${extraVariable}) {
+        StartRealtimeClientSession(targetAgentId: $targetAgentId, conversationId: $conversationId, lastSessionId: $lastSessionId, preferredModelId: $preferredModelId, clientToolsJson: $clientToolsJson, coAgentId: $coAgentId, configOverridesJson: $configOverridesJson, recordingConsent: $recordingConsent, recordingStartedAt: $recordingStartedAt, mediaCollectionId: $mediaCollectionId, applicationId: $applicationId, appContextJson: $appContextJson, conversationBranchId: $conversationBranchId${extraArgument}) {
+          AgentSessionId
+          ConversationId
+          Provider
+          Model
+          EphemeralToken
+          ExpiresAt
+          SessionConfigJson
+          ModelName
+          NarrationInstructionsTemplate
+          PriorChannelStatesJson${extraField}
+        }
+      }
+    `;
+    }
+}
+//# sourceMappingURL=session-launcher.js.map