@memberjunction/realtime-runtime 0.0.0 → 6.2.0-edge.1

package/dist/channels/base-realtime-channel-client.js

@@ -0,0 +1,233 @@
+/**
+ * Base class for CLIENT-SIDE interactive-channel plugins (per
+ * `plans/ai-agent-sessions.md` → "Interactive Channels" / "Pluggable Channel Interfaces").
+ *
+ * An interactive channel is a bidirectional surface the session's single realtime agent
+ * both PERCEIVES and ACTS UPON (whiteboard, shared doc, map, …). A concrete plugin
+ * contributes everything the channel needs, so the session service / call overlay carry
+ * ZERO channel-specific wiring:
+ *
+ *  1. a CLIENT-EXECUTED TOOL SET ({@link GetToolDefinitions}, declared to the realtime
+ *     model at session mint) plus the local executor ({@link ApplyAgentTool}) the host
+ *     routes `{@link ToolNamePrefix}*` calls to — the ACTION direction;
+ *  2. a STATE→CONTEXT SERIALIZER policy — the plugin owns its state engine and pushes
+ *     coalesced deltas through {@link RealtimeChannelContext.SendContextNote} — the
+ *     PERCEPTION direction;
+ *  3. an OPTIONAL ANGULAR SURFACE ({@link GetSurfaceComponent}) the overlay creates dynamically
+ *     in a channel tab, handed back through {@link BindSurface} so the plugin wires its own
+ *     inputs/outputs (the host never knows the component's API). A channel may be **server-only**
+ *     (no rendered surface) — e.g. a bridge-contributed meeting-controls or native-whiteboard
+ *     channel whose surface lives on the external platform, not in MJ. Such a channel returns
+ *     `null` from {@link GetSurfaceComponent} ({@link HasSurface} is `false`) and the overlay
+ *     simply skips its tab while still wiring its tools + perception;
+ *  4. a STATE OF RECORD ({@link SerializeState}, persisted via
+ *     {@link RealtimeChannelContext.RequestSave} under {@link ChannelName}).
+ *
+ * ### Registration & resolution (mirrors the realtime model drivers)
+ * Concrete plugins are `@RegisterClass(BaseRealtimeChannelClient, '<ClientPluginClass>')`
+ * and are resolved at session start from the `MJ: AI Agent Channels` registry: each ACTIVE
+ * row's `ClientPluginClass` is the ClassFactory key (exactly how `BaseRealtimeClient`
+ * drivers resolve by provider key). Ship a `Load<YourChannel>()` no-op alongside the class
+ * and call it from a static code path to defeat tree-shaking.
+ *
+ * ### Lifecycle — ONE INSTANCE PER SESSION (not a singleton)
+ * `ClassFactory.CreateInstance` → {@link Initialize}(ctx) → zero or more
+ * {@link BindSurface}/{@link UnbindSurface} cycles (the surface pane is created/destroyed
+ * with the overlay's tab panel, e.g. collapse/expand) → {@link Dispose} at teardown.
+ * {@link ApplyAgentTool} MUST work with NO surface bound (apply to the state engine
+ * directly; skip the UI garnish) — tool calls can arrive while the panel is collapsed.
+ *
+ * @typeParam TSurface The plugin's Angular surface component type. The host only ever
+ *   sees the default (`object`) — the typed parameter exists so concrete plugins get a
+ *   fully typed {@link BindSurface} without casts.
+ */
+export class BaseRealtimeChannelClient {
+    constructor() {
+        /**
+         * The host context, available from {@link Initialize} until {@link Dispose}.
+         * `null` outside that window — guard with `?.` in any code that can run early/late.
+         */
+        this.Context = null;
+        /**
+         * Max time {@link ResolveAgentSessionId} waits for the session id to bind before giving up, and the
+         * poll interval it re-checks on. Protected so tests can shrink the wait; production keeps the
+         * defaults (the real mint race is sub-second, 8s is generous headroom).
+         */
+        this.SessionIdWaitTimeoutMs = 8000;
+        this.SessionIdWaitIntervalMs = 200;
+    }
+    /**
+     * OPTIONAL accent color for the channel's tab (a CSS color string, e.g. an `hsl()` /
+     * token). When a plugin supplies one, the overlay paints the tab's dot + active underline
+     * with it; when omitted (the default `null`), the overlay derives a stable, deterministic
+     * color from the {@link ChannelName} so every channel still reads as a distinct, colored
+     * surface. A channel only overrides this to enforce a specific brand accent.
+     */
+    get TabColor() {
+        return null;
+    }
+    /**
+     * The Angular component the overlay creates dynamically as this channel's tab pane, or `null`
+     * for a **server-only** channel that renders no MJ surface (its surface, if any, lives on the
+     * external platform — e.g. a bridge-contributed native whiteboard or meeting-controls channel).
+     *
+     * When this returns `null`, the overlay renders NO tab for the channel and never calls
+     * {@link BindSurface}/{@link UnbindSurface} — but the channel's tools ({@link GetToolDefinitions} /
+     * {@link ApplyAgentTool}) and perception ({@link RealtimeChannelContext.SendContextNote}) still run.
+     * A created surface instance is handed straight back via {@link BindSurface}; the host treats it as
+     * opaque.
+     *
+     * Default: `null` (server-only). A channel with a rendered surface overrides this to return its
+     * component type.
+     */
+    GetSurfaceComponent() {
+        return null;
+    }
+    /**
+     * Whether this channel has a rendered MJ surface ({@link GetSurfaceComponent} returns non-null).
+     * The overlay uses this to decide whether to register a surface tab; server-only channels are
+     * `false`. Override only if surface availability must be decided WITHOUT constructing the type
+     * (the default calls {@link GetSurfaceComponent} once).
+     */
+    HasSurface() {
+        return this.GetSurfaceComponent() != null;
+    }
+    /**
+     * The channel's FIRST-RUN INTRO content, or `null` when the channel offers no onboarding.
+     * The overlay shows this once per channel per user — the first time the user opens this
+     * channel's surface tab — and remembers "seen" via the user's settings (NOT localStorage),
+     * so it never re-appears on later sessions or other devices.
+     *
+     * Default: `null` (no intro). The base Voice/text channel has no plugin at all, so it never
+     * shows an intro; an interactive channel with a surface worth explaining (whiteboard, remote
+     * browser, …) overrides this to return its {@link ChannelOnboardingDetails}. A plugin that
+     * doesn't override it simply shows nothing — onboarding is strictly opt-in.
+     */
+    GetOnboardingDetails() {
+        return null;
+    }
+    /**
+     * Called by the host when the surface component is being destroyed (tab panel
+     * collapsed / overlay torn down). Drop the instance reference and unsubscribe any
+     * output subscriptions — after this, {@link ApplyAgentTool} runs in its no-surface
+     * mode. Default: no-op.
+     */
+    UnbindSurface() {
+        // default: nothing to release
+    }
+    /**
+     * Binds the host context and invokes the {@link OnInitialize} hook. Called exactly once
+     * per session, right after ClassFactory instantiation and before any tool call or
+     * surface bind.
+     */
+    Initialize(ctx) {
+        this.Context = ctx;
+        this.OnInitialize();
+    }
+    /**
+     * Subclass hook invoked from {@link Initialize} once {@link Context} is bound — wire
+     * state-engine subscriptions (e.g. state change → `Context.RequestSave(...)`) here.
+     * Default: no-op.
+     */
+    OnInitialize() {
+        // default: nothing to initialize
+    }
+    /**
+     * Subclass hook invoked once the realtime session is connected and live (the client driver
+     * is created, connected, and media tracks negotiated). Channels that establish media bridges
+     * (e.g. video streaming) can start them here when `Context.Client` is available.
+     * Default: no-op.
+     */
+    OnSessionStarted() {
+        // default: nothing to do
+    }
+    /**
+     * Resolves the live {@link RealtimeChannelContext.AgentSessionID}, briefly WAITING for it when it
+     * isn't bound yet rather than giving up instantly. `AgentSessionID` is a live getter over the
+     * session service's current id: it reads `null` in the window BEFORE the session mints (the
+     * realtime model can fire a tool call the very first beat it connects, before `mintSession`
+     * resolves) and again AFTER teardown. Server-backed tool paths (e.g. the Remote Browser channel's
+     * `browser_*` tools) call this instead of reading `Context?.AgentSessionID` synchronously, so a tool
+     * invoked a beat early WAITS for the session to come live — defense-in-depth against the
+     * "session id missing" race — instead of returning a hard failure to the model.
+     *
+     * Returns the id as soon as it's non-null (the common path resolves immediately, no delay), or
+     * `null` if it's still unbound after {@link SessionIdWaitTimeoutMs} — or the channel was
+     * {@link Dispose}d in the meantime (`Context` goes null, so we stop waiting on a torn-down session).
+     */
+    async ResolveAgentSessionId() {
+        const immediate = this.Context?.AgentSessionID ?? null;
+        if (immediate) {
+            return immediate;
+        }
+        const intervalMs = Math.max(1, this.SessionIdWaitIntervalMs);
+        for (let waited = 0; waited < this.SessionIdWaitTimeoutMs; waited += intervalMs) {
+            await new Promise((resolve) => setTimeout(resolve, intervalMs));
+            // Context goes null on Dispose() — the session is gone, stop waiting.
+            if (!this.Context) {
+                return null;
+            }
+            const id = this.Context.AgentSessionID;
+            if (id) {
+                return id;
+            }
+        }
+        return this.Context?.AgentSessionID ?? null;
+    }
+    /**
+     * Serializes the channel's current state of record (the payload persisted on the
+     * session's channel row), or `null` when the channel keeps no persistent state.
+     * Default: `null`.
+     */
+    SerializeState() {
+        return null;
+    }
+    /**
+     * Restores a PRIOR session's saved channel state (the payload a previous session
+     * persisted via {@link SerializeState} / {@link RealtimeChannelContext.RequestSave}).
+     * Invoked by the session host AFTER {@link Initialize} and BEFORE any surface binding,
+     * when a prior session's saved state exists for this channel.
+     *
+     * Returns `true` when the state was applied; `false` when the channel ignored it —
+     * either because it keeps no persistent state (this default) or because the payload was
+     * malformed/incompatible. Implementations MUST be tolerant: never throw on bad input,
+     * just return `false` and start fresh.
+     */
+    RestoreState(stateJson) {
+        return false;
+    }
+    /**
+     * The focus pill's "exit" affordance, routed by the overlay to the channel that holds
+     * focus. Implementations should leave focus mode through their OWN surface (so surface
+     * toggles stay in sync), ultimately emitting `Context.SetFocusMode(false)`. The overlay
+     * defensively clears its layout flag as well, so a no-op default is safe.
+     */
+    RequestFocusExit() {
+        // default: the overlay's defensive clear handles it
+    }
+    /**
+     * Media tracks this client channel can SOURCE — samples flowing into the model.
+     * Default `[]`.
+     */
+    GetSourcedTracks() {
+        return [];
+    }
+    /**
+     * Media tracks this client channel can SINK — samples flowing from the model OUT.
+     * Default `[]`.
+     */
+    GetSunkTracks() {
+        return [];
+    }
+    /**
+     * Tears the plugin down at session end: release the surface binding, unsubscribe
+     * state-engine subscriptions, then drop the context. Subclasses overriding this MUST
+     * call `super.Dispose()`. Any final state save has already been flushed by the host
+     * (the debounced {@link RealtimeChannelContext.RequestSave} pipeline) before disposal.
+     */
+    Dispose() {
+        this.UnbindSurface();
+        this.Context = null;
+    }
+}
+//# sourceMappingURL=base-realtime-channel-client.js.map

package/dist/channels/base-realtime-channel-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-realtime-channel-client.js","sourceRoot":"","sources":["../../src/channels/base-realtime-channel-client.ts"],"names":[],"mappings":"AAkMA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,MAAM,OAAgB,yBAAyB;IAA/C;QACE;;;WAGG;QACO,YAAO,GAAkC,IAAI,CAAC;QA+IxD;;;;WAIG;QACO,2BAAsB,GAAG,IAAI,CAAC;QAC9B,4BAAuB,GAAG,GAAG,CAAC;IAgG1C,CAAC;IA/NC;;;;;;OAMG;IACH,IAAW,QAAQ;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;IAoBD;;;;;;;;;;;;;OAaG;IACI,mBAAmB;QACxB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;OAKG;IACI,UAAU;QACf,OAAO,IAAI,CAAC,mBAAmB,EAAE,IAAI,IAAI,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;OAUG;IACI,oBAAoB;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAYD;;;;;OAKG;IACI,aAAa;QAClB,8BAA8B;IAChC,CAAC;IAED;;;;OAIG;IACI,UAAU,CAAC,GAA2B;QAC3C,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;QACnB,IAAI,CAAC,YAAY,EAAE,CAAC;IACtB,CAAC;IAED;;;;OAIG;IACO,YAAY;QACpB,iCAAiC;IACnC,CAAC;IAED;;;;;OAKG;IACI,gBAAgB;QACrB,yBAAyB;IAC3B,CAAC;IAUD;;;;;;;;;;;;;OAaG;IACO,KAAK,CAAC,qBAAqB;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;QACvD,IAAI,SAAS,EAAE,CAAC;YACd,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,uBAAuB,CAAC,CAAC;QAC7D,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,sBAAsB,EAAE,MAAM,IAAI,UAAU,EAAE,CAAC;YAChF,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC;YACtE,sEAAsE;YACtE,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;gBAClB,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC;YACvC,IAAI,EAAE,EAAE,CAAC;gBACP,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC,OAAO,EAAE,cAAc,IAAI,IAAI,CAAC;IAC9C,CAAC;IAED;;;;OAIG;IACI,cAAc;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;;;OAUG;IACI,YAAY,CAAC,SAAiB;QACnC,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACI,gBAAgB;QACrB,oDAAoD;IACtD,CAAC;IAED;;;OAGG;IACI,gBAAgB;QACrB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;OAGG;IACI,aAAa;QAClB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED;;;;;OAKG;IACI,OAAO;QACZ,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACtB,CAAC;CACF"}

package/dist/hosts/IRealtimeMediaHost.d.ts

@@ -0,0 +1,136 @@
+/**
+ * @fileoverview The media seam between the framework-agnostic realtime session runtime and
+ * whatever platform is hosting it.
+ *
+ * ## Why this interface exists
+ *
+ * The realtime co-agent session orchestration — mint, driver resolution, transcript relay, tool
+ * relay, delegation narration, channel lifecycle, usage relay, teardown — is pure TypeScript and
+ * runs identically in a browser, in React Native, or in a Node test harness. Exactly **one** line
+ * of it was not: microphone acquisition, which was hard-coded to
+ * `navigator.mediaDevices.getUserMedia({ audio: true })`.
+ *
+ * That was never meant to live in the runtime. The Real-Time Co-Agents guide states the contract
+ * plainly — *"the host acquires the mic (it owns the permission UX)"* — because microphone
+ * permission is a **product** decision that differs per platform: a browser shows the URL-bar
+ * prompt, iOS shows a system sheet gated on an `Info.plist` usage string, Android runs the
+ * runtime-permission flow. The runtime has no business making that call; it only needs the
+ * resulting stream. This interface makes that pre-existing contract explicit instead of implied.
+ *
+ * ## Implementations
+ *
+ * - **Browser** — `getUserMedia({ audio: true })` and the global `RTCPeerConnection`.
+ * - **React Native** — the `react-native-webrtc` equivalents, which polyfill both APIs natively
+ *   and additionally give the platform's acoustic echo cancellation, noise suppression and jitter
+ *   buffering for free.
+ * - **Test harness** — a synthetic stream, so a session can be driven end to end with no hardware.
+ *
+ * ## A note on `MediaStream`
+ *
+ * `MediaStream` is referenced as a **type only**. It is erased at compile time, it is already in
+ * this repo's base `lib` (`tsconfig.server.json`), and `react-native-webrtc` ships a conforming
+ * implementation — so naming it here costs nothing and invents no parallel abstraction. The
+ * runtime never *constructs* one; it only receives it from the host and hands it to the realtime
+ * client driver, whose `Connect()` already takes exactly this type.
+ */
+/**
+ * The platform capabilities the realtime session runtime needs but cannot provide itself.
+ *
+ * Implement one of these per host. Every member is intentionally coarse — the runtime asks for an
+ * outcome ("give me a microphone"), never for a mechanism ("call getUserMedia with these
+ * constraints"), so hosts stay free to satisfy it however their platform requires.
+ */
+export interface IRealtimeMediaHost {
+    /**
+     * Acquires the user's microphone, prompting for permission if the platform requires it.
+     *
+     * The host owns the entire permission experience, including any pre-permission priming UI and
+     * the decision about what to do when permission is permanently denied.
+     *
+     * @returns the live audio stream to hand to the realtime driver.
+     * @throws if permission is denied or no input device is available. The runtime treats a throw
+     *         as a failed session start and tears down cleanly — hosts do **not** need to
+     *         pre-check permission to avoid a half-open session.
+     */
+    AcquireMicrophone(): Promise<MediaStream>;
+    /**
+     * OPTIONAL: returns the platform's audio state to what it was before
+     * {@link AcquireMicrophone} changed it.
+     *
+     * Acquiring a microphone is not always a symmetric act. A browser hands back a stream and
+     * nothing else changes, so most hosts omit this. iOS is the counter-example: a voice call
+     * requires putting the shared audio session into a record-and-play category with the speaker
+     * route, and that setting outlives the call — every later sound in the app plays through the
+     * call route, at call volume, until something puts it back.
+     *
+     * Called by the runtime on teardown, after the microphone tracks are stopped, on every exit
+     * path including a failed start. Best-effort: a rejection is logged and swallowed, because
+     * restoring audio state is never worth failing the end of a call over.
+     */
+    ReleaseMicrophone?(): Promise<void> | void;
+    /**
+     * OPTIONAL: creates a recorder for this session's audio, when the platform can record and the
+     * user has consented.
+     *
+     * Returning `null` — or omitting the member entirely — disables recording for the session.
+     * That is a fully supported configuration, not a degraded one: recording is consent-gated and
+     * many hosts will never offer it. The runtime's session clock is anchored independently of the
+     * recorder precisely so that unrecorded sessions still produce correct per-turn timings.
+     *
+     * The returned recorder is **unstarted** — the runtime calls {@link IRealtimeSessionRecorder.Start}
+     * once it knows whether the agent's remote stream is already available.
+     */
+    CreateRecorder?(): IRealtimeSessionRecorder | null;
+}
+/**
+ * The recording capability a host may optionally provide.
+ *
+ * Mirrors the browser recorder's existing surface so the runtime's call sites are unchanged by the
+ * extraction. Every method is best-effort by contract: a recorder that fails mid-session must
+ * degrade to "no recording" rather than failing the call, because audio capture is never worth
+ * dropping a live conversation over.
+ */
+export interface IRealtimeSessionRecorder {
+    /** `false` when capture could not start (unsupported platform, no permission). */
+    readonly IsRecording: boolean;
+    /** Capture sample rate, used to label the header-less PCM16 crash-recovery shards. */
+    readonly SampleRate: number;
+    /**
+     * Container MIME type of the FINAL consolidated recording.
+     *
+     * Read it BEFORE {@link StopAndEncode} — implementations are permitted to clear it on stop,
+     * which is why the runtime captures it first.
+     */
+    readonly MimeType: string;
+    /**
+     * Begins capture of the microphone, mixing in the agent's audio when it is already available.
+     *
+     * `remoteStream` is usually `null` here: on WebRTC the agent's track commonly lands slightly
+     * after the connection resolves, so the runtime also wires {@link AttachRemoteStream}.
+     */
+    Start(micStream: MediaStream, remoteStream: MediaStream | null): void;
+    /** Mixes the agent's audio in once its track arrives, so the recording carries both sides. */
+    AttachRemoteStream(stream: MediaStream): void;
+    /** Milliseconds into the recording, used to stamp per-turn cue offsets into a seekable file. */
+    NowOffsetMs(): number;
+    /** Waveform peaks computed during capture; survives {@link StopAndEncode}. */
+    GetPeaks(): number[];
+    /**
+     * Returns audio captured since the previous snapshot, **already base64-encoded**, or `null`
+     * when nothing new is pending.
+     *
+     * Encoding lives behind this seam deliberately: browsers reach for `Blob` + `FileReader`,
+     * React Native reads a file off disk, and a test harness may hold bytes in memory. The runtime
+     * only forwards the string to the server, so it should never learn which of those it is.
+     *
+     * Shards are header-less raw little-endian PCM16 — recovery is concatenate-in-order then
+     * WAV-wrap. The canonical seekable file is the consolidated {@link StopAndEncode} upload.
+     */
+    SnapshotNewSegmentBase64(): Promise<string | null>;
+    /**
+     * Stops capture and returns the consolidated recording **already base64-encoded**, or `null`
+     * when nothing was captured. Idempotent.
+     */
+    StopAndEncode(): Promise<string | null>;
+}
+//# sourceMappingURL=IRealtimeMediaHost.d.ts.map

package/dist/hosts/IRealtimeMediaHost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IRealtimeMediaHost.d.ts","sourceRoot":"","sources":["../../src/hosts/IRealtimeMediaHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;;;;;;;OAUG;IACH,iBAAiB,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAE1C;;;;;;;;;;;;;OAaG;IACH,iBAAiB,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAE3C;;;;;;;;;;;OAWG;IACH,cAAc,CAAC,IAAI,wBAAwB,GAAG,IAAI,CAAC;CACtD;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,wBAAwB;IACrC,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAE9B,sFAAsF;IACtF,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAE1B;;;;;OAKG;IACH,KAAK,CAAC,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,GAAG,IAAI,GAAG,IAAI,CAAC;IAEtE,8FAA8F;IAC9F,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAE9C,gGAAgG;IAChG,WAAW,IAAI,MAAM,CAAC;IAEtB,8EAA8E;IAC9E,QAAQ,IAAI,MAAM,EAAE,CAAC;IAErB;;;;;;;;;;OAUG;IACH,wBAAwB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAEnD;;;OAGG;IACH,aAAa,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC3C"}

package/dist/hosts/IRealtimeMediaHost.js

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview The media seam between the framework-agnostic realtime session runtime and
+ * whatever platform is hosting it.
+ *
+ * ## Why this interface exists
+ *
+ * The realtime co-agent session orchestration — mint, driver resolution, transcript relay, tool
+ * relay, delegation narration, channel lifecycle, usage relay, teardown — is pure TypeScript and
+ * runs identically in a browser, in React Native, or in a Node test harness. Exactly **one** line
+ * of it was not: microphone acquisition, which was hard-coded to
+ * `navigator.mediaDevices.getUserMedia({ audio: true })`.
+ *
+ * That was never meant to live in the runtime. The Real-Time Co-Agents guide states the contract
+ * plainly — *"the host acquires the mic (it owns the permission UX)"* — because microphone
+ * permission is a **product** decision that differs per platform: a browser shows the URL-bar
+ * prompt, iOS shows a system sheet gated on an `Info.plist` usage string, Android runs the
+ * runtime-permission flow. The runtime has no business making that call; it only needs the
+ * resulting stream. This interface makes that pre-existing contract explicit instead of implied.
+ *
+ * ## Implementations
+ *
+ * - **Browser** — `getUserMedia({ audio: true })` and the global `RTCPeerConnection`.
+ * - **React Native** — the `react-native-webrtc` equivalents, which polyfill both APIs natively
+ *   and additionally give the platform's acoustic echo cancellation, noise suppression and jitter
+ *   buffering for free.
+ * - **Test harness** — a synthetic stream, so a session can be driven end to end with no hardware.
+ *
+ * ## A note on `MediaStream`
+ *
+ * `MediaStream` is referenced as a **type only**. It is erased at compile time, it is already in
+ * this repo's base `lib` (`tsconfig.server.json`), and `react-native-webrtc` ships a conforming
+ * implementation — so naming it here costs nothing and invents no parallel abstraction. The
+ * runtime never *constructs* one; it only receives it from the host and hands it to the realtime
+ * client driver, whose `Connect()` already takes exactly this type.
+ */
+export {};
+//# sourceMappingURL=IRealtimeMediaHost.js.map

package/dist/hosts/IRealtimeMediaHost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IRealtimeMediaHost.js","sourceRoot":"","sources":["../../src/hosts/IRealtimeMediaHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG"}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @fileoverview Public entry point for `@memberjunction/realtime-runtime`.
+ *
+ * Framework-agnostic orchestration for MemberJunction **client-direct realtime co-agent sessions**:
+ * minting a session, resolving the provider's client driver, wiring transcripts and captions,
+ * relaying tool calls, pacing delegation progress narration, managing interactive channels, relaying
+ * usage, and tearing all of it down cleanly.
+ *
+ * ## Why this package exists
+ *
+ * This code shipped inside `@memberjunction/ng-conversations` as an `@Injectable` Angular service.
+ * It was never Angular-specific — its own header noted it stays component-free so it "must stay
+ * importable in plain-node tests" — but living in an Angular package made it unusable from any
+ * other host. A React Native app, a React or Vue surface, or a headless test harness had no way to
+ * drive a realtime session except by reimplementing ~2,700 lines that already existed, and then
+ * watching the two copies drift apart at the next protocol change.
+ *
+ * Extracting it follows the precedent set by `@memberjunction/conversations-runtime`, which did the
+ * same for chat orchestration. The Angular service remains — as a thin adapter that supplies the
+ * browser's media host and the `@Injectable` shell — so Explorer is unchanged.
+ *
+ * ## What a host must provide
+ *
+ * Exactly one thing: an {@link IRealtimeMediaHost}. Microphone acquisition and audio recording are
+ * platform decisions (permission UX, container format, where bytes live), so they sit behind that
+ * seam. Everything else in a realtime session is portable and lives here.
+ *
+ * @module @memberjunction/realtime-runtime
+ */
+export { RealtimeSessionRuntime } from './session/RealtimeSessionRuntime.js';
+export { REALTIME_RECORDING_CONSENT_KEY, type RealtimeConnectionState, type RealtimeCaption, type RealtimeDelegationProgress, type RealtimeDelegationResult, type RealtimeClientToolHandler, type RealtimeChannelFocusEvent, type RealtimeDelegationNarration, type RealtimeThoughtNarration, type StartRealtimeClientSessionResult, type RealtimeSessionRunOptions, } from './session/RealtimeSessionRuntime.js';
+export { type IRealtimeMediaHost, type IRealtimeSessionRecorder, } from './hosts/IRealtimeMediaHost.js';
+export { BaseRealtimeChannelClient, type RealtimeChannelContext, type RealtimeSurfaceComponentType, type ChannelOnboardingDetails, } from './channels/base-realtime-channel-client.js';
+export { ParseDelegationResultJson, type ParsedDelegationArtifact, type ParsedDelegationResult, FormatToolName, } from './session/delegation-result-parser.js';
+export { BuildNarrationInstructions, DefaultNarrationInstructions, type NarrationBuildOptions, } from './narration/narration-template.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAG1E,OAAO,EACH,8BAA8B,EAC9B,KAAK,uBAAuB,EAC5B,KAAK,eAAe,EACpB,KAAK,0BAA0B,EAC/B,KAAK,wBAAwB,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,yBAAyB,EAC9B,KAAK,2BAA2B,EAChC,KAAK,wBAAwB,EAC7B,KAAK,gCAAgC,EACrC,KAAK,yBAAyB,GACjC,MAAM,kCAAkC,CAAC;AAG1C,OAAO,EACH,KAAK,kBAAkB,EACvB,KAAK,wBAAwB,GAChC,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EACH,yBAAyB,EACzB,KAAK,sBAAsB,EAC3B,KAAK,4BAA4B,EACjC,KAAK,wBAAwB,GAChC,MAAM,yCAAyC,CAAC;AAGjD,OAAO,EACH,yBAAyB,EACzB,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,cAAc,GACjB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACH,0BAA0B,EAC1B,4BAA4B,EAC5B,KAAK,qBAAqB,GAC7B,MAAM,gCAAgC,CAAC"}

package/dist/index.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Public entry point for `@memberjunction/realtime-runtime`.
+ *
+ * Framework-agnostic orchestration for MemberJunction **client-direct realtime co-agent sessions**:
+ * minting a session, resolving the provider's client driver, wiring transcripts and captions,
+ * relaying tool calls, pacing delegation progress narration, managing interactive channels, relaying
+ * usage, and tearing all of it down cleanly.
+ *
+ * ## Why this package exists
+ *
+ * This code shipped inside `@memberjunction/ng-conversations` as an `@Injectable` Angular service.
+ * It was never Angular-specific — its own header noted it stays component-free so it "must stay
+ * importable in plain-node tests" — but living in an Angular package made it unusable from any
+ * other host. A React Native app, a React or Vue surface, or a headless test harness had no way to
+ * drive a realtime session except by reimplementing ~2,700 lines that already existed, and then
+ * watching the two copies drift apart at the next protocol change.
+ *
+ * Extracting it follows the precedent set by `@memberjunction/conversations-runtime`, which did the
+ * same for chat orchestration. The Angular service remains — as a thin adapter that supplies the
+ * browser's media host and the `@Injectable` shell — so Explorer is unchanged.
+ *
+ * ## What a host must provide
+ *
+ * Exactly one thing: an {@link IRealtimeMediaHost}. Microphone acquisition and audio recording are
+ * platform decisions (permission UX, container format, where bytes live), so they sit behind that
+ * seam. Everything else in a realtime session is portable and lives here.
+ *
+ * @module @memberjunction/realtime-runtime
+ */
+// The session runtime itself — the orchestration a host subclasses or composes.
+export { RealtimeSessionRuntime } from './session/RealtimeSessionRuntime.js';
+// Session-facing types a host or UI binds to.
+export { REALTIME_RECORDING_CONSENT_KEY, } from './session/RealtimeSessionRuntime.js';
+// Interactive channel plugin contract — the client half of the channel registry.
+export { BaseRealtimeChannelClient, } from './channels/base-realtime-channel-client.js';
+// Delegation result parsing + narration instruction assembly.
+export { ParseDelegationResultJson, FormatToolName, } from './session/delegation-result-parser.js';
+export { BuildNarrationInstructions, DefaultNarrationInstructions, } from './narration/narration-template.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,gFAAgF;AAChF,OAAO,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAE1E,8CAA8C;AAC9C,OAAO,EACH,8BAA8B,GAWjC,MAAM,kCAAkC,CAAC;AAQ1C,iFAAiF;AACjF,OAAO,EACH,yBAAyB,GAI5B,MAAM,yCAAyC,CAAC;AAEjD,8DAA8D;AAC9D,OAAO,EACH,yBAAyB,EAGzB,cAAc,GACjB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACH,0BAA0B,EAC1B,4BAA4B,GAE/B,MAAM,gCAAgC,CAAC"}

package/dist/narration/narration-template.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Pure helpers for building the one-off spoken progress-narration instructions a
+ * realtime voice session sends to the model while delegated work runs.
+ *
+ * The instruction text is DB-driven: the server resolves the `Realtime Co-Agent - Progress Narration`
+ * prompt's `TemplateText` at session start and threads it to the browser. The template may use:
+ *   - `{{ progressMessage }}`  — the aggregated progress digest (one or more updates, oldest first)
+ *   - `{{ priorNarrations }}`  — what the model has ALREADY said aloud for this task (so it can
+ *                                continue the story instead of repeating itself)
+ *   - `{{ updateNumber }}`     — 1-based count of spoken updates for this task
+ * When a deployment hasn't synced that prompt yet, the built-in
+ * {@link DefaultNarrationInstructions} fallback keeps narration working with the same semantics.
+ */
+/** Options accompanying the progress digest when building narration instructions. */
+export interface NarrationBuildOptions {
+    /** The narration utterances the model has already spoken for this task, oldest first. */
+    PriorNarrations?: string[];
+    /** 1-based number of this spoken update within the current task. */
+    UpdateNumber?: number;
+}
+/**
+ * Builds the built-in (fallback) narration instructions — same semantics as the DB template:
+ * first person, varied phrasing that continues from what was already said, no repeats.
+ *
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param options Prior narrations + update number for phrasing variation/chaining.
+ * @returns The complete spoken-update instruction text.
+ */
+export declare function DefaultNarrationInstructions(digest: string, options?: NarrationBuildOptions): string;
+/**
+ * Builds the narration instructions from the server-provided template by substituting
+ * `{{ progressMessage }}`, `{{ priorNarrations }}`, and `{{ updateNumber }}` (space and no-space
+ * variants). Falls back to {@link DefaultNarrationInstructions} when the template is absent or
+ * blank (deployments that haven't synced the narration prompt).
+ *
+ * @param template The DB-driven instruction template, or `null`/`undefined` when unavailable.
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param options Prior narrations + update number for phrasing variation/chaining.
+ * @returns The complete spoken-update instruction text.
+ */
+export declare function BuildNarrationInstructions(template: string | null | undefined, digest: string, options?: NarrationBuildOptions): string;
+//# sourceMappingURL=narration-template.d.ts.map

package/dist/narration/narration-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"narration-template.d.ts","sourceRoot":"","sources":["../../src/narration/narration-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,qFAAqF;AACrF,MAAM,WAAW,qBAAqB;IACpC,yFAAyF;IACzF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAuBD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAcpG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,qBAAqB,GAC9B,MAAM,CAQR"}

package/dist/narration/narration-template.js

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Pure helpers for building the one-off spoken progress-narration instructions a
+ * realtime voice session sends to the model while delegated work runs.
+ *
+ * The instruction text is DB-driven: the server resolves the `Realtime Co-Agent - Progress Narration`
+ * prompt's `TemplateText` at session start and threads it to the browser. The template may use:
+ *   - `{{ progressMessage }}`  — the aggregated progress digest (one or more updates, oldest first)
+ *   - `{{ priorNarrations }}`  — what the model has ALREADY said aloud for this task (so it can
+ *                                continue the story instead of repeating itself)
+ *   - `{{ updateNumber }}`     — 1-based count of spoken updates for this task
+ * When a deployment hasn't synced that prompt yet, the built-in
+ * {@link DefaultNarrationInstructions} fallback keeps narration working with the same semantics.
+ */
+const PROGRESS_TOKENS = ['{{ progressMessage }}', '{{progressMessage}}'];
+const PRIOR_TOKENS = ['{{ priorNarrations }}', '{{priorNarrations}}'];
+const NUMBER_TOKENS = ['{{ updateNumber }}', '{{updateNumber}}'];
+/** Replaces every occurrence of each token with the value. */
+function replaceTokens(text, tokens, value) {
+    let out = text;
+    for (const t of tokens) {
+        out = out.split(t).join(value);
+    }
+    return out;
+}
+/** Formats the prior spoken narrations for injection ("none yet" when this is the first update). */
+function formatPriorNarrations(prior) {
+    if (!prior || prior.length === 0) {
+        return 'Nothing yet — this is your first spoken update for this task.';
+    }
+    return prior.map((p) => `- "${p}"`).join('\n');
+}
+/**
+ * Builds the built-in (fallback) narration instructions — same semantics as the DB template:
+ * first person, varied phrasing that continues from what was already said, no repeats.
+ *
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param options Prior narrations + update number for phrasing variation/chaining.
+ * @returns The complete spoken-update instruction text.
+ */
+export function DefaultNarrationInstructions(digest, options) {
+    const updateNumber = options?.UpdateNumber ?? 1;
+    return (`Live progress on the work YOU are doing for the user (oldest first): ${digest}. ` +
+        `This is spoken update #${updateNumber} for this task. You have already told the user:\n` +
+        `${formatPriorNarrations(options?.PriorNarrations)}\n` +
+        `Say ONE short, natural sentence in the FIRST PERSON continuing the story of what you are doing. ` +
+        `For the first update something like "I'm pulling that up now" is fine; for later updates VARY the ` +
+        `phrasing and build on what you last said ("Got the first part — grabbing the rest", "Almost there, ` +
+        `just double-checking the numbers") instead of repeating an "I'm now…" pattern. Never repeat ` +
+        `information you've already conveyed — only add what's new. Strictly first person: the words "it" ` +
+        `and the agent's name must not be the subject of your sentence, and never say generic filler like ` +
+        `"it's still running in the background".`);
+}
+/**
+ * Builds the narration instructions from the server-provided template by substituting
+ * `{{ progressMessage }}`, `{{ priorNarrations }}`, and `{{ updateNumber }}` (space and no-space
+ * variants). Falls back to {@link DefaultNarrationInstructions} when the template is absent or
+ * blank (deployments that haven't synced the narration prompt).
+ *
+ * @param template The DB-driven instruction template, or `null`/`undefined` when unavailable.
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param options Prior narrations + update number for phrasing variation/chaining.
+ * @returns The complete spoken-update instruction text.
+ */
+export function BuildNarrationInstructions(template, digest, options) {
+    if (!template || template.trim().length === 0) {
+        return DefaultNarrationInstructions(digest, options);
+    }
+    let out = replaceTokens(template, PROGRESS_TOKENS, digest);
+    out = replaceTokens(out, PRIOR_TOKENS, formatPriorNarrations(options?.PriorNarrations));
+    out = replaceTokens(out, NUMBER_TOKENS, String(options?.UpdateNumber ?? 1));
+    return out;
+}
+//# sourceMappingURL=narration-template.js.map

package/dist/narration/narration-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"narration-template.js","sourceRoot":"","sources":["../../src/narration/narration-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,MAAM,eAAe,GAAG,CAAC,uBAAuB,EAAE,qBAAqB,CAAC,CAAC;AACzE,MAAM,YAAY,GAAG,CAAC,uBAAuB,EAAE,qBAAqB,CAAC,CAAC;AACtE,MAAM,aAAa,GAAG,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,CAAC;AAEjE,8DAA8D;AAC9D,SAAS,aAAa,CAAC,IAAY,EAAE,MAAgB,EAAE,KAAa;IAClE,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oGAAoG;AACpG,SAAS,qBAAqB,CAAC,KAA2B;IACxD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,+DAA+D,CAAC;IACzE,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAc,EAAE,OAA+B;IAC1F,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,CAAC,CAAC;IAChD,OAAO,CACL,wEAAwE,MAAM,IAAI;QAClF,0BAA0B,YAAY,mDAAmD;QACzF,GAAG,qBAAqB,CAAC,OAAO,EAAE,eAAe,CAAC,IAAI;QACtD,kGAAkG;QAClG,oGAAoG;QACpG,qGAAqG;QACrG,8FAA8F;QAC9F,mGAAmG;QACnG,mGAAmG;QACnG,yCAAyC,CAC1C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAmC,EACnC,MAAc,EACd,OAA+B;IAE/B,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9C,OAAO,4BAA4B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,GAAG,GAAG,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,CAAC,CAAC;IAC3D,GAAG,GAAG,aAAa,CAAC,GAAG,EAAE,YAAY,EAAE,qBAAqB,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;IACxF,GAAG,GAAG,aAAa,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5E,OAAO,GAAG,CAAC;AACb,CAAC"}