@memberjunction/realtime-runtime 6.2.0-edge.2 → 6.2.0-edge.4

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

package/dist/session/session-launcher.js.map

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/realtime-runtime",
   "type": "module",
-  "version": "6.2.0-edge.2",
+  "version": "6.2.0-edge.4",
   "description": "MemberJunction: Framework-agnostic Realtime Session Runtime — client-direct realtime co-agent session orchestration (mint, driver resolution, transcripts, tool relay, delegation narration, channel lifecycle, usage relay). Pure TypeScript, zero UX dependencies. Consumable from browser (Angular/React/Vue), React Native, or Node test harnesses.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,14 +11,14 @@
   "author": "MemberJunction.com",
   "license": "BUSL-1.1",
   "dependencies": {
-    "@memberjunction/ai": "6.2.0-edge.2",
-    "@memberjunction/ai-core-plus": "6.2.0-edge.2",
-    "@memberjunction/ai-engine-base": "6.2.0-edge.2",
-    "@memberjunction/ai-realtime-client": "6.2.0-edge.2",
-    "@memberjunction/core": "6.2.0-edge.2",
-    "@memberjunction/core-entities": "6.2.0-edge.2",
-    "@memberjunction/global": "6.2.0-edge.2",
-    "@memberjunction/graphql-dataprovider": "6.2.0-edge.2",
+    "@memberjunction/ai": "6.2.0-edge.4",
+    "@memberjunction/ai-core-plus": "6.2.0-edge.4",
+    "@memberjunction/ai-engine-base": "6.2.0-edge.4",
+    "@memberjunction/ai-realtime-client": "6.2.0-edge.4",
+    "@memberjunction/core": "6.2.0-edge.4",
+    "@memberjunction/core-entities": "6.2.0-edge.4",
+    "@memberjunction/global": "6.2.0-edge.4",
+    "@memberjunction/graphql-dataprovider": "6.2.0-edge.4",
     "rxjs": "^7.8.2"
   },
   "devDependencies": {