@memberjunction/ai 5.40.2 → 5.42.0

package/dist/generic/baseRealtime.js

@@ -0,0 +1,134 @@
+import { BaseModel } from "./baseModel.js";
+/**
+ * Base class for real-time, full-duplex, tool-calling models.
+ *
+ * `BaseRealtimeModel` is the lowest-level primitive for streaming, bidirectional models
+ * (e.g. Google Gemini Live, OpenAI GPT Realtime, and — as a fast-follow — the Eleven Labs
+ * stack). It is a sibling of {@link BaseModel}-derived capability classes such as `BaseLLM`
+ * and `BaseAudioGenerator`, and is resolved through the MemberJunction `ClassFactory` by
+ * `AIModelType` + `DriverClass`.
+ *
+ * The contract is deliberately **modality-agnostic** — *streaming, full-duplex, tool-calling* —
+ * so the same primitive covers voice now and video later. It is distinct from
+ * `BaseAudioGenerator`, which is request/response STT/TTS (a different shape, not the
+ * real-time path).
+ *
+ * **Driver registration:** Concrete drivers ship in the respective `@memberjunction/ai-*`
+ * provider packages and self-register via the class factory, e.g.
+ * `@RegisterClass(BaseRealtimeModel, 'GeminiRealtime')`. The associated `MJ: AI Models`
+ * are typed with the `AIModelType` value **`Realtime`**.
+ *
+ * ## DRIVER AUTHOR OBLIGATIONS
+ *
+ * Hard-won, provider-independent rules every server-side realtime driver (and its
+ * client-direct twin — see `BaseRealtimeClient` in `@memberjunction/ai-realtime-client`)
+ * MUST honor. Most were paid for in live debugging; do not relearn them:
+ *
+ * 1. **Silent exit from "speaking" after a tool call.** When the model emits a tool call,
+ *    the host typically shows its own busy ("thinking") indicator while the tool executes.
+ *    A driver that surfaces UI state must leave any "speaking" state *silently* (no state
+ *    emission) at tool-call time so the turn's trailing frames don't clobber the host's
+ *    indicator.
+ * 2. **Busy-flag release on tool-call emission (deadlock guard).** A tool-call frame means
+ *    the model has yielded the floor pending the result. Any internal "response active" /
+ *    busy flag MUST be cleared at that point — otherwise the eventual `SendToolResult` (or
+ *    a queued send) deadlocks waiting for a turn boundary that will never arrive until
+ *    after the result is sent.
+ * 3. **Playback flush + honest playback reporting on interruption.** On a true barge-in the
+ *    driver (or its client twin) must flush any locally-owned audio playback and report
+ *    "audio playing = false" promptly — stale queued audio after an interruption is a
+ *    product bug, not a nicety.
+ * 4. **Text injection must NOT echo a user transcript.** A "send typed text" capability
+ *    must not synthesize a user-role transcript event for the injected text — the host owns
+ *    the local echo and would render the message twice.
+ * 5. **Tool-result delivery invariant.** Every tool result fed back via
+ *    {@link IRealtimeSession.SendToolResult} must EVENTUALLY be voiced/processed by the
+ *    model and must never be dropped. If the provider rejects overlapping generation
+ *    triggers, the driver queues the result's trigger behind the in-flight response and
+ *    flushes it at the next turn boundary.
+ * 6. **Token/credential expiry surfaces as a FATAL error.** When the session's credential
+ *    dies (ephemeral token expiry, auth revocation), the driver must surface it through
+ *    {@link IRealtimeSession.OnError} with `Fatal: true` so the consumer finalizes cleanly
+ *    instead of idling forever on a dead socket.
+ * 7. **"Ready" only after the session config is applied.** A driver (or client twin) must
+ *    not report the session as live/listening until the server-built session config
+ *    (system prompt + tools) has actually been applied to the provider socket — otherwise
+ *    early turns run against an unconfigured model.
+ * 8. **`SessionConfig` is a private pact.** The {@link ClientRealtimeSessionConfig.SessionConfig}
+ *    payload a server driver mints is consumed ONLY by the same-keyed client driver. Hosts
+ *    and intermediaries treat it as an opaque blob; its shape may change between the two
+ *    driver halves without notice.
+ *
+ * @abstract
+ */
+export class BaseRealtimeModel extends BaseModel {
+    /**
+     * Whether this driver can mint an ephemeral, server-scoped client credential for a
+     * **client-direct** realtime session (the browser opens its own provider socket using a
+     * short-lived token the server minted).
+     *
+     * Defaults to `false`. Providers that support browser-direct sessions override this to `true`
+     * and implement {@link CreateClientSession}. The server-bridged topology (where the provider
+     * socket lives on the server, via {@link StartSession}) is supported by every driver regardless
+     * of this flag.
+     *
+     * @returns `true` if {@link CreateClientSession} is supported; `false` otherwise.
+     */
+    get SupportsClientDirect() {
+        return false;
+    }
+    /**
+     * Mints an ephemeral, server-scoped client credential plus a provider-native session config for
+     * a **client-direct** realtime session.
+     *
+     * In the client-direct topology the browser owns the provider socket (e.g. WebRTC), but the
+     * **server** still controls the prompt and tool set: it mints a short-lived token and hands back
+     * a {@link ClientRealtimeSessionConfig} whose `SessionConfig` the matching client driver applies
+     * when it opens its socket. This keeps prompt/tool authority server-side even though the media
+     * plane is client-direct.
+     *
+     * Not every provider supports this (some only expose a server-bridged socket), so this is a
+     * concrete method that throws by default rather than an abstract one — that would force every
+     * existing and future driver to implement it. Providers that support it override
+     * {@link SupportsClientDirect} to `true` and override this method.
+     *
+     * @param _params The session parameters (system prompt, tools, model, config bag).
+     * @returns A promise resolving to the minted {@link ClientRealtimeSessionConfig}.
+     * @throws Always, unless overridden by a provider that supports client-direct sessions.
+     */
+    async CreateClientSession(_params) {
+        throw new Error(`${this.constructor.name} does not support client-direct realtime sessions`);
+    }
+    /**
+     * Whether this driver's sessions carry a **video** track in addition to audio — i.e. the model
+     * accepts video input (it can "see" the user's camera) and/or emits video output (a talking-head
+     * avatar / generated video), in sync with audio.
+     *
+     * Defaults to `false` (audio-only — today's realtime models). Video-capable drivers (a native
+     * multimodal realtime model, or an avatar provider) override this to `true`. The session's media
+     * plane is media-tagged ({@link IRealtimeSession.SendInput} takes a {@link RealtimeMediaKind};
+     * {@link IRealtimeSession.OnVideoOutput} delivers video-out), so a video session reuses the entire
+     * realtime contract — only the media frames gain a `video` kind. Resolution prefers a video-capable
+     * model when an agent requests video, and degrades to audio-only otherwise.
+     *
+     * @returns `true` if sessions can carry video; `false` (audio-only) otherwise.
+     */
+    get SupportsVideo() {
+        return false;
+    }
+    /**
+     * The provider-native voice ids this model can speak with (e.g. OpenAI `alloy`/`echo`/`shimmer`). The
+     * model/driver is the authoritative owner of "what voices do I support", so each driver declares its
+     * own — used to populate the dev voice picker. Default empty (a driver that hasn't declared voices
+     * yields no picker options, falling back to the configured/default voice).
+     *
+     * NOTE: this is the near-term, driver-owned source of truth. Long term this should move to metadata so
+     * providers that let users add their OWN voices (e.g. ElevenLabs) can be enumerated dynamically.
+     *
+     * @returns The supported voice ids (id + human label), or `[]` when none are declared.
+     */
+    get SupportedVoices() {
+        return [];
+    }
+}
+//# sourceMappingURL=baseRealtime.js.map

package/dist/generic/baseRealtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseRealtime.js","sourceRoot":"","sources":["../../src/generic/baseRealtime.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAoBxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,MAAM,OAAgB,iBAAkB,SAAQ,SAAS;IAcrD;;;;;;;;;;;OAWG;IACH,IAAW,oBAAoB;QAC3B,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACI,KAAK,CAAC,mBAAmB,CAAC,OAA8B;QAC3D,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,WAAW,CAAC,IAAI,mDAAmD,CAAC,CAAC;IACjG,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,IAAW,aAAa;QACpB,OAAO,KAAK,CAAC;IACjB,CAAC;IAED;;;;;;;;;;OAUG;IACH,IAAW,eAAe;QACtB,OAAO,EAAE,CAAC;IACd,CAAC;CACJ"}

package/dist/generic/baseRealtimeChannelServer.d.ts

@@ -0,0 +1,235 @@
+/**
+ * @fileoverview Base class for SERVER-SIDE interactive-channel plugins — the server half of the
+ * channel plugin registry (`MJ: AI Agent Channels.ServerPluginClass`), mirroring the client half
+ * (`BaseRealtimeChannelClient` in `@memberjunction/ng-conversations`, resolved from the same
+ * registry's `ClientPluginClass`).
+ *
+ * Lives beside {@link import('./baseRealtime.js').BaseRealtimeModel} because it is a server-side
+ * realtime primitive with the same constraint: zero MJ dependencies past `@memberjunction/global`.
+ * The DB-aware resolution/orchestration half (reading the channel registry, one-instance-per-session
+ * bookkeeping) lives in `@memberjunction/ai-agents` (`RealtimeChannelServerHost`).
+ *
+ * @module @memberjunction/ai
+ * @author MemberJunction.com
+ */
+import { RealtimeToolDefinition } from './baseRealtime.js';
+/**
+ * Why an agent session was closed — the server-side channel plugin's view of the session-close
+ * provenance. Mirrors the `MJ: AI Agent Sessions.CloseReason` value list (`SessionCloseReason` in
+ * `@memberjunction/server`): `'Explicit'` (user hang-up), `'Janitor'` (orphan reconciliation),
+ * `'Shutdown'` (graceful host drain), `'Error'` (failure-path teardown). `null` reaches the plugin
+ * only for legacy rows closed before the column existed (or when the reason was never stamped).
+ */
+export type RealtimeChannelCloseReason = 'Explicit' | 'Janitor' | 'Shutdown' | 'Error';
+/**
+ * Immutable session facts handed to a {@link BaseRealtimeChannelServer} at
+ * {@link BaseRealtimeChannelServer.Initialize}. Deliberately **plain data** (string ids, no entity
+ * or `UserInfo` objects) so the base contract stays free of `@memberjunction/core` — concrete
+ * plugins that need richer server context load it themselves in the packages they ship in.
+ */
+export interface RealtimeChannelServerContext {
+    /** The durable `MJ: AI Agent Sessions` row id this plugin instance is bound to. */
+    AgentSessionID: string;
+    /** The session's agent id (`AIAgentSession.AgentID` — the co-agent on realtime voice sessions). */
+    AgentID: string;
+    /** The owning user's id (`AIAgentSession.UserID`) — ownership is enforced host-side on every relay. */
+    UserID: string;
+    /** The conversation the session is attached to, or `null` when the session carries none. */
+    ConversationID: string | null;
+    /**
+     * **Optional perception sink** — feeds a background context note into the live realtime model
+     * (the server-side counterpart of the client channel's `RealtimeChannelContext.SendContextNote`).
+     * The host wires this to `IRealtimeSession.SendContextNote` when the provider supports mid-session
+     * context injection; a server-side channel calls it to keep the agent aware of what is happening
+     * on its surface (a hand went up, who is speaking, time remaining) WITHOUT forcing a spoken reply.
+     *
+     * Optional because not every provider supports injecting conversation items into an open session
+     * (some only accept media frames + tool results), and because the host may construct the context
+     * before a live session exists. Channels MUST call it null-safely (`this.Context?.SendContextNote?.(…)`).
+     *
+     * @param text The perception note to surface to the model (plain text; the channel owns any framing).
+     */
+    SendContextNote?(text: string): void;
+}
+/**
+ * The result of a server-side channel tool execution ({@link BaseRealtimeChannelServer.ExecuteServerTool}),
+ * fed back to the realtime model as the `tool_response`.
+ *
+ * Deliberately small and serializable — the host (`RealtimeChannelServerHost`) wraps a thrown error
+ * into a `{ Success: false }` result so the model always receives a consistent response, and the
+ * transport layer (`RealtimeSessionRunner`) serializes `{ success, output }` to the exact JSON shape
+ * the model expects (identical to {@link import('../..').RealtimeToolBrokerDeps} non-target tooling).
+ */
+export interface ServerChannelToolResult {
+    /** Whether the tool executed successfully. */
+    Success: boolean;
+    /**
+     * The textual outcome to feed back to the model: a description of what changed on success, or
+     * the error to surface on failure (so the model can narrate it — spoken-error-handling).
+     */
+    Output: string;
+}
+/**
+ * Base class for SERVER-SIDE interactive-channel plugins (per `plans/ai-agent-sessions.md` →
+ * "Pluggable Interfaces (`IAgentChannelServer` & `IAgentChannelClient`)").
+ *
+ * ### Relationship to the plan's `IAgentChannelServer`
+ * The plan's interface anticipates **server-bridged media** — a channel that owns sockets, receives
+ * demultiplexed `OnClientMessage` payloads from a unified `ISessionTransport`, and streams data back.
+ * That transport plane is an independent, not-yet-built track. What exists TODAY is the
+ * **client-direct** topology: channel plugins execute in the browser
+ * (`BaseRealtimeChannelClient`), and the server's per-channel touchpoints are the durable lifecycle
+ * events — session minted, channel state-of-record saved, session closed. This base class is the
+ * pragmatic adaptation to that reality:
+ *
+ * - `Initialize(ctx)` / `Dispose()` keep the plan's lifecycle bracket (and mirror the client half).
+ * - `OnClientMessage` / `SendToClient` / socket ownership are **deferred** with the transport track —
+ *   when `ISessionTransport` lands, this class grows an injected-transport overload rather than the
+ *   plan's raw-socket form (the plan itself refines them away; see its "Unified Session Transport").
+ * - The lifecycle hooks below ({@link OnSessionStarted} / {@link OnChannelStateSave} /
+ *   {@link OnSessionClosed}) are the events the shipping session machinery actually emits.
+ *
+ * ### Registration & resolution (mirrors the client half exactly)
+ * Concrete plugins are `@RegisterClass(BaseRealtimeChannelServer, '<ServerPluginClass>')` and are
+ * resolved at session start from the ACTIVE `MJ: AI Agent Channels` rows: each row's
+ * `ServerPluginClass` is the ClassFactory key. Rows whose key has no registration are skipped with
+ * a log — never fatal; a session always proceeds with whatever server plugins resolve. Ship a
+ * `Load<YourChannel>Server()` no-op beside the class and call it from a static code path so
+ * bundlers cannot tree-shake the registration away.
+ *
+ * ### Lifecycle — ONE INSTANCE PER SESSION (not a singleton)
+ * `ClassFactory.CreateInstance` → {@link Initialize}(ctx) → {@link OnSessionStarted} → zero or more
+ * {@link OnChannelStateSave} calls (one per debounced client state-save landing on the server) →
+ * {@link OnSessionClosed}(reason) → {@link Dispose}. Disposal is deliberately **deferred briefly**
+ * after close by the host so the client's final post-close state flush (a legitimate, contract-
+ * sanctioned late save) still routes through the plugin.
+ *
+ * ### Failure tolerance (hard contract)
+ * Every hook is invoked inside a host-side try/catch: a throwing plugin is logged and the session
+ * proceeds untouched — a channel plugin can never break a live call or block persistence.
+ * Implementations should still prefer returning benign results over throwing.
+ *
+ * ### Server-executed tool contribution (Phase 2 — now wired)
+ * A server-side channel may contribute a **dynamic, runtime-computed** tool vocabulary the agent can
+ * invoke server-side (a bot has no browser, so these execute on the server rather than client-side
+ * like the {@link import('../..').BaseRealtimeChannelClient} half). The two hooks:
+ *
+ * - {@link GetServerToolDefinitions} — returns the channel's server-executed tool declarations. May
+ *   be **runtime-computed** (per session / per platform state), not only constants — this is what
+ *   lets a bridge-contributed channel (e.g. Meeting Controls, a Zoom native whiteboard) declare a
+ *   tool set that only exists because of the live connection. Default: `[]` (a state-only channel
+ *   like the whiteboard contributes no server tools).
+ * - {@link ExecuteServerTool} — executes ONE of this channel's tools and returns the result. Default:
+ *   a structured "not implemented" error (never throws), so a channel that declares tools but forgets
+ *   to implement execution fails loudly-but-safely rather than crashing the session.
+ *
+ * The per-session host ({@link RealtimeChannelServerHost}) aggregates every live plugin's
+ * {@link GetServerToolDefinitions} into the session's tool set (feeding
+ * `RealtimeSessionRunner.ServerChannelTools`) and routes each `{@link ToolNamePrefix}*` tool call back
+ * to the owning plugin's {@link ExecuteServerTool}. Tool-name collisions across channels are avoided
+ * by each channel's {@link ToolNamePrefix} (mirroring the client half's `ToolNamePrefix`).
+ *
+ * @remarks
+ * Socket/media members (`OnClientMessage`, `SendToClient`) remain deferred with the unified-transport
+ * track — when `ISessionTransport` lands, this class grows an injected-transport overload rather than
+ * the plan's raw-socket form.
+ */
+export declare abstract class BaseRealtimeChannelServer {
+    /**
+     * The bound session context, available from {@link Initialize} until {@link Dispose}.
+     * `null` outside that window — guard with `?.` in any code that can run early/late.
+     */
+    protected Context: RealtimeChannelServerContext | null;
+    /**
+     * The channel definition name — MUST match the `MJ: AI Agent Channels` row's `Name`
+     * (e.g. `'Whiteboard'`). The host routes {@link OnChannelStateSave} by the registry row's
+     * name and warns when a resolved plugin's `ChannelName` disagrees with its row.
+     */
+    abstract get ChannelName(): string;
+    /**
+     * The shared name prefix of every server-executed tool this channel contributes (e.g.
+     * `'MeetingControls_'`). The host routes any tool call whose name starts with this prefix to
+     * THIS plugin's {@link ExecuteServerTool}, which is what prevents tool-name collisions when
+     * multiple channels are active in one session. A channel that contributes no server tools may
+     * leave the default empty string (the host then never routes any call to it).
+     *
+     * Mirrors the client half's `ToolNamePrefix`. Default: `''` (no server tools).
+     */
+    get ToolNamePrefix(): string;
+    /**
+     * Returns this channel's **server-executed** tool declarations — the tools the agent can invoke
+     * on this channel that run server-side (a bot has no browser). May be **runtime-computed**: the
+     * returned set can depend on the live session, the connected platform, or current channel state,
+     * so a bridge-contributed channel can declare a vocabulary that only exists because of the live
+     * connection. Every tool's `Name` SHOULD start with {@link ToolNamePrefix} so the host can route
+     * its execution back here unambiguously.
+     *
+     * Invoked by {@link RealtimeChannelServerHost} when assembling the session's tool set (after the
+     * plugin's {@link OnSessionStarted}). Default: `[]` (a state-only channel contributes none).
+     *
+     * @returns The channel's server-executed tool definitions (possibly empty).
+     */
+    GetServerToolDefinitions(): RealtimeToolDefinition[];
+    /**
+     * Executes ONE of this channel's server-side tools (a tool whose name starts with
+     * {@link ToolNamePrefix}) and returns the result fed back to the model as the `tool_response`.
+     *
+     * Implementations should NOT throw — return a `{ Success: false, Output }` result so the model can
+     * narrate the failure. The host additionally wraps anything thrown into a structured error, so a
+     * throwing implementation can never break the live session. The default implementation returns a
+     * structured "not implemented" error, so a channel that declares tools via
+     * {@link GetServerToolDefinitions} but forgets to implement execution fails safely and visibly.
+     *
+     * @param toolName The full tool name the model invoked (begins with {@link ToolNamePrefix}).
+     * @param argsJson The raw arguments JSON string the model emitted for the call.
+     * @returns The execution result (or a structured error), synchronously or as a promise.
+     */
+    ExecuteServerTool(toolName: string, argsJson: string): ServerChannelToolResult | Promise<ServerChannelToolResult>;
+    /**
+     * Binds the session context and invokes the {@link OnInitialize} hook. Called exactly once per
+     * session by the host, right after ClassFactory instantiation and before any lifecycle hook.
+     */
+    Initialize(ctx: RealtimeChannelServerContext): void;
+    /**
+     * Subclass hook invoked from {@link Initialize} once {@link Context} is bound — allocate any
+     * per-session state here. Default: no-op.
+     */
+    protected OnInitialize(): void;
+    /**
+     * Invoked by the host immediately after {@link Initialize}, when the durable session record has
+     * been persisted (`Status = 'Active'`) — the session id, agent, and conversation are all in
+     * {@link Context}. Default: no-op.
+     */
+    OnSessionStarted(): Promise<void>;
+    /**
+     * Invoked when the client's debounced channel-state save for THIS channel lands on the server,
+     * BEFORE the state is persisted onto the session's `MJ: AI Agent Session Channels` row.
+     *
+     * The plugin may **validate/normalize** the payload: return a replacement JSON string to persist
+     * instead of `stateJson`, or `null` to persist the original unchanged (the default). The host
+     * treats a thrown error, a non-string, or an empty string as "keep the original" — a plugin can
+     * therefore never lose a state save, only improve it.
+     *
+     * @param stateJson The raw state-of-record payload the client submitted (already size-capped
+     *   host-side).
+     * @returns The normalized payload to persist, or `null` to keep `stateJson` as-is.
+     */
+    OnChannelStateSave(stateJson: string): Promise<string | null>;
+    /**
+     * Invoked when the session is closed — from ANY close path: the user's explicit hang-up, the
+     * janitor's orphan/staleness sweeps, the graceful shutdown drain, or an error-path teardown
+     * (the reason says which). Fired once per session; {@link Dispose} follows after the host's
+     * brief post-close linger window (during which late state saves still route here first).
+     * Default: no-op.
+     *
+     * @param closeReason The persisted close provenance, or `null` for legacy/unstamped rows.
+     */
+    OnSessionClosed(closeReason: RealtimeChannelCloseReason | null): Promise<void>;
+    /**
+     * Tears the plugin down: release any per-session resources, then drop the context. Subclasses
+     * overriding this MUST call `super.Dispose()`. Invoked by the host after the post-close linger
+     * window elapses (or immediately when the host is configured with no linger).
+     */
+    Dispose(): void;
+}
+//# sourceMappingURL=baseRealtimeChannelServer.d.ts.map

package/dist/generic/baseRealtimeChannelServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseRealtimeChannelServer.d.ts","sourceRoot":"","sources":["../../src/generic/baseRealtimeChannelServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,MAAM,0BAA0B,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,OAAO,CAAC;AAEvF;;;;;GAKG;AACH,MAAM,WAAW,4BAA4B;IACzC,mFAAmF;IACnF,cAAc,EAAE,MAAM,CAAC;IAEvB,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAC;IAEhB,uGAAuG;IACvG,MAAM,EAAE,MAAM,CAAC;IAEf,4FAA4F;IAC5F,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAE9B;;;;;;;;;;;;OAYG;IACH,eAAe,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,uBAAuB;IACpC,8CAA8C;IAC9C,OAAO,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,8BAAsB,yBAAyB;IAC3C;;;OAGG;IACH,SAAS,CAAC,OAAO,EAAE,4BAA4B,GAAG,IAAI,CAAQ;IAE9D;;;;OAIG;IACH,aAAoB,WAAW,IAAI,MAAM,CAAC;IAE1C;;;;;;;;OAQG;IACH,IAAW,cAAc,IAAI,MAAM,CAElC;IAED;;;;;;;;;;;;OAYG;IACI,wBAAwB,IAAI,sBAAsB,EAAE;IAI3D;;;;;;;;;;;;;OAaG;IACI,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC;IAIxH;;;OAGG;IACI,UAAU,CAAC,GAAG,EAAE,4BAA4B,GAAG,IAAI;IAK1D;;;OAGG;IACH,SAAS,CAAC,YAAY,IAAI,IAAI;IAI9B;;;;OAIG;IACU,gBAAgB,IAAI,OAAO,CAAC,IAAI,CAAC;IAI9C;;;;;;;;;;;;OAYG;IACU,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAI1E;;;;;;;;OAQG;IACU,eAAe,CAAC,WAAW,EAAE,0BAA0B,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3F;;;;OAIG;IACI,OAAO,IAAI,IAAI;CAGzB"}

package/dist/generic/baseRealtimeChannelServer.js

@@ -0,0 +1,193 @@
+/**
+ * @fileoverview Base class for SERVER-SIDE interactive-channel plugins — the server half of the
+ * channel plugin registry (`MJ: AI Agent Channels.ServerPluginClass`), mirroring the client half
+ * (`BaseRealtimeChannelClient` in `@memberjunction/ng-conversations`, resolved from the same
+ * registry's `ClientPluginClass`).
+ *
+ * Lives beside {@link import('./baseRealtime.js').BaseRealtimeModel} because it is a server-side
+ * realtime primitive with the same constraint: zero MJ dependencies past `@memberjunction/global`.
+ * The DB-aware resolution/orchestration half (reading the channel registry, one-instance-per-session
+ * bookkeeping) lives in `@memberjunction/ai-agents` (`RealtimeChannelServerHost`).
+ *
+ * @module @memberjunction/ai
+ * @author MemberJunction.com
+ */
+/**
+ * Base class for SERVER-SIDE interactive-channel plugins (per `plans/ai-agent-sessions.md` →
+ * "Pluggable Interfaces (`IAgentChannelServer` & `IAgentChannelClient`)").
+ *
+ * ### Relationship to the plan's `IAgentChannelServer`
+ * The plan's interface anticipates **server-bridged media** — a channel that owns sockets, receives
+ * demultiplexed `OnClientMessage` payloads from a unified `ISessionTransport`, and streams data back.
+ * That transport plane is an independent, not-yet-built track. What exists TODAY is the
+ * **client-direct** topology: channel plugins execute in the browser
+ * (`BaseRealtimeChannelClient`), and the server's per-channel touchpoints are the durable lifecycle
+ * events — session minted, channel state-of-record saved, session closed. This base class is the
+ * pragmatic adaptation to that reality:
+ *
+ * - `Initialize(ctx)` / `Dispose()` keep the plan's lifecycle bracket (and mirror the client half).
+ * - `OnClientMessage` / `SendToClient` / socket ownership are **deferred** with the transport track —
+ *   when `ISessionTransport` lands, this class grows an injected-transport overload rather than the
+ *   plan's raw-socket form (the plan itself refines them away; see its "Unified Session Transport").
+ * - The lifecycle hooks below ({@link OnSessionStarted} / {@link OnChannelStateSave} /
+ *   {@link OnSessionClosed}) are the events the shipping session machinery actually emits.
+ *
+ * ### Registration & resolution (mirrors the client half exactly)
+ * Concrete plugins are `@RegisterClass(BaseRealtimeChannelServer, '<ServerPluginClass>')` and are
+ * resolved at session start from the ACTIVE `MJ: AI Agent Channels` rows: each row's
+ * `ServerPluginClass` is the ClassFactory key. Rows whose key has no registration are skipped with
+ * a log — never fatal; a session always proceeds with whatever server plugins resolve. Ship a
+ * `Load<YourChannel>Server()` no-op beside the class and call it from a static code path so
+ * bundlers cannot tree-shake the registration away.
+ *
+ * ### Lifecycle — ONE INSTANCE PER SESSION (not a singleton)
+ * `ClassFactory.CreateInstance` → {@link Initialize}(ctx) → {@link OnSessionStarted} → zero or more
+ * {@link OnChannelStateSave} calls (one per debounced client state-save landing on the server) →
+ * {@link OnSessionClosed}(reason) → {@link Dispose}. Disposal is deliberately **deferred briefly**
+ * after close by the host so the client's final post-close state flush (a legitimate, contract-
+ * sanctioned late save) still routes through the plugin.
+ *
+ * ### Failure tolerance (hard contract)
+ * Every hook is invoked inside a host-side try/catch: a throwing plugin is logged and the session
+ * proceeds untouched — a channel plugin can never break a live call or block persistence.
+ * Implementations should still prefer returning benign results over throwing.
+ *
+ * ### Server-executed tool contribution (Phase 2 — now wired)
+ * A server-side channel may contribute a **dynamic, runtime-computed** tool vocabulary the agent can
+ * invoke server-side (a bot has no browser, so these execute on the server rather than client-side
+ * like the {@link import('../..').BaseRealtimeChannelClient} half). The two hooks:
+ *
+ * - {@link GetServerToolDefinitions} — returns the channel's server-executed tool declarations. May
+ *   be **runtime-computed** (per session / per platform state), not only constants — this is what
+ *   lets a bridge-contributed channel (e.g. Meeting Controls, a Zoom native whiteboard) declare a
+ *   tool set that only exists because of the live connection. Default: `[]` (a state-only channel
+ *   like the whiteboard contributes no server tools).
+ * - {@link ExecuteServerTool} — executes ONE of this channel's tools and returns the result. Default:
+ *   a structured "not implemented" error (never throws), so a channel that declares tools but forgets
+ *   to implement execution fails loudly-but-safely rather than crashing the session.
+ *
+ * The per-session host ({@link RealtimeChannelServerHost}) aggregates every live plugin's
+ * {@link GetServerToolDefinitions} into the session's tool set (feeding
+ * `RealtimeSessionRunner.ServerChannelTools`) and routes each `{@link ToolNamePrefix}*` tool call back
+ * to the owning plugin's {@link ExecuteServerTool}. Tool-name collisions across channels are avoided
+ * by each channel's {@link ToolNamePrefix} (mirroring the client half's `ToolNamePrefix`).
+ *
+ * @remarks
+ * Socket/media members (`OnClientMessage`, `SendToClient`) remain deferred with the unified-transport
+ * track — when `ISessionTransport` lands, this class grows an injected-transport overload rather than
+ * the plan's raw-socket form.
+ */
+export class BaseRealtimeChannelServer {
+    constructor() {
+        /**
+         * The bound session 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;
+    }
+    /**
+     * The shared name prefix of every server-executed tool this channel contributes (e.g.
+     * `'MeetingControls_'`). The host routes any tool call whose name starts with this prefix to
+     * THIS plugin's {@link ExecuteServerTool}, which is what prevents tool-name collisions when
+     * multiple channels are active in one session. A channel that contributes no server tools may
+     * leave the default empty string (the host then never routes any call to it).
+     *
+     * Mirrors the client half's `ToolNamePrefix`. Default: `''` (no server tools).
+     */
+    get ToolNamePrefix() {
+        return '';
+    }
+    /**
+     * Returns this channel's **server-executed** tool declarations — the tools the agent can invoke
+     * on this channel that run server-side (a bot has no browser). May be **runtime-computed**: the
+     * returned set can depend on the live session, the connected platform, or current channel state,
+     * so a bridge-contributed channel can declare a vocabulary that only exists because of the live
+     * connection. Every tool's `Name` SHOULD start with {@link ToolNamePrefix} so the host can route
+     * its execution back here unambiguously.
+     *
+     * Invoked by {@link RealtimeChannelServerHost} when assembling the session's tool set (after the
+     * plugin's {@link OnSessionStarted}). Default: `[]` (a state-only channel contributes none).
+     *
+     * @returns The channel's server-executed tool definitions (possibly empty).
+     */
+    GetServerToolDefinitions() {
+        return [];
+    }
+    /**
+     * Executes ONE of this channel's server-side tools (a tool whose name starts with
+     * {@link ToolNamePrefix}) and returns the result fed back to the model as the `tool_response`.
+     *
+     * Implementations should NOT throw — return a `{ Success: false, Output }` result so the model can
+     * narrate the failure. The host additionally wraps anything thrown into a structured error, so a
+     * throwing implementation can never break the live session. The default implementation returns a
+     * structured "not implemented" error, so a channel that declares tools via
+     * {@link GetServerToolDefinitions} but forgets to implement execution fails safely and visibly.
+     *
+     * @param toolName The full tool name the model invoked (begins with {@link ToolNamePrefix}).
+     * @param argsJson The raw arguments JSON string the model emitted for the call.
+     * @returns The execution result (or a structured error), synchronously or as a promise.
+     */
+    ExecuteServerTool(toolName, argsJson) {
+        return { Success: false, Output: `Server tool '${toolName}' is declared by channel '${this.ChannelName}' but has no execution implementation.` };
+    }
+    /**
+     * Binds the session context and invokes the {@link OnInitialize} hook. Called exactly once per
+     * session by the host, right after ClassFactory instantiation and before any lifecycle hook.
+     */
+    Initialize(ctx) {
+        this.Context = ctx;
+        this.OnInitialize();
+    }
+    /**
+     * Subclass hook invoked from {@link Initialize} once {@link Context} is bound — allocate any
+     * per-session state here. Default: no-op.
+     */
+    OnInitialize() {
+        // default: nothing to initialize
+    }
+    /**
+     * Invoked by the host immediately after {@link Initialize}, when the durable session record has
+     * been persisted (`Status = 'Active'`) — the session id, agent, and conversation are all in
+     * {@link Context}. Default: no-op.
+     */
+    async OnSessionStarted() {
+        // default: nothing to do at session start
+    }
+    /**
+     * Invoked when the client's debounced channel-state save for THIS channel lands on the server,
+     * BEFORE the state is persisted onto the session's `MJ: AI Agent Session Channels` row.
+     *
+     * The plugin may **validate/normalize** the payload: return a replacement JSON string to persist
+     * instead of `stateJson`, or `null` to persist the original unchanged (the default). The host
+     * treats a thrown error, a non-string, or an empty string as "keep the original" — a plugin can
+     * therefore never lose a state save, only improve it.
+     *
+     * @param stateJson The raw state-of-record payload the client submitted (already size-capped
+     *   host-side).
+     * @returns The normalized payload to persist, or `null` to keep `stateJson` as-is.
+     */
+    async OnChannelStateSave(stateJson) {
+        return null; // default: persist the client's payload untouched
+    }
+    /**
+     * Invoked when the session is closed — from ANY close path: the user's explicit hang-up, the
+     * janitor's orphan/staleness sweeps, the graceful shutdown drain, or an error-path teardown
+     * (the reason says which). Fired once per session; {@link Dispose} follows after the host's
+     * brief post-close linger window (during which late state saves still route here first).
+     * Default: no-op.
+     *
+     * @param closeReason The persisted close provenance, or `null` for legacy/unstamped rows.
+     */
+    async OnSessionClosed(closeReason) {
+        // default: nothing to do at session close
+    }
+    /**
+     * Tears the plugin down: release any per-session resources, then drop the context. Subclasses
+     * overriding this MUST call `super.Dispose()`. Invoked by the host after the post-close linger
+     * window elapses (or immediately when the host is configured with no linger).
+     */
+    Dispose() {
+        this.Context = null;
+    }
+}
+//# sourceMappingURL=baseRealtimeChannelServer.js.map

package/dist/generic/baseRealtimeChannelServer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"baseRealtimeChannelServer.js","sourceRoot":"","sources":["../../src/generic/baseRealtimeChannelServer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAoEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,MAAM,OAAgB,yBAAyB;IAA/C;QACI;;;WAGG;QACO,YAAO,GAAwC,IAAI,CAAC;IAyHlE,CAAC;IAhHG;;;;;;;;OAQG;IACH,IAAW,cAAc;QACrB,OAAO,EAAE,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;OAYG;IACI,wBAAwB;QAC3B,OAAO,EAAE,CAAC;IACd,CAAC;IAED;;;;;;;;;;;;;OAaG;IACI,iBAAiB,CAAC,QAAgB,EAAE,QAAgB;QACvD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,QAAQ,6BAA6B,IAAI,CAAC,WAAW,wCAAwC,EAAE,CAAC;IACrJ,CAAC;IAED;;;OAGG;IACI,UAAU,CAAC,GAAiC;QAC/C,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC;QACnB,IAAI,CAAC,YAAY,EAAE,CAAC;IACxB,CAAC;IAED;;;OAGG;IACO,YAAY;QAClB,iCAAiC;IACrC,CAAC;IAED;;;;OAIG;IACI,KAAK,CAAC,gBAAgB;QACzB,0CAA0C;IAC9C,CAAC;IAED;;;;;;;;;;;;OAYG;IACI,KAAK,CAAC,kBAAkB,CAAC,SAAiB;QAC7C,OAAO,IAAI,CAAC,CAAC,kDAAkD;IACnE,CAAC;IAED;;;;;;;;OAQG;IACI,KAAK,CAAC,eAAe,CAAC,WAA8C;QACvE,0CAA0C;IAC9C,CAAC;IAED;;;;OAIG;IACI,OAAO;QACV,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC;IACxB,CAAC;CACJ"}

package/dist/generic/embed.types.d.ts

@@ -1,10 +1,14 @@
 import { BaseParams, ModelUsage } from "./baseModel.js";
+import { ChatMessageContent } from "./chat.types.js";
 export type EmbedTextParams = BaseParams & {
     text: string;
 };
 export type EmbedTextsParams = BaseParams & {
     texts: string[];
 };
+export type EmbedContentParams = BaseParams & {
+    content: ChatMessageContent;
+};
 export type EmbedResult = {
     object: 'object' | 'list';
     model: string;
@@ -16,4 +20,5 @@ export type EmbedTextResult = EmbedResult & {
 export type EmbedTextsResult = EmbedResult & {
     vectors: number[][];
 };
+export type EmbedContentResult = EmbedTextResult;
 //# sourceMappingURL=embed.types.d.ts.map

package/dist/generic/embed.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"embed.types.d.ts","sourceRoot":"","sources":["../../src/generic/embed.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAErD,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG;IACvC,IAAI,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IACxC,KAAK,EAAE,MAAM,EAAE,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACtB,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,UAAU,CAAC;CAC1B,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IACxC,MAAM,EAAE,MAAM,EAAE,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG;IACzC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAA;CACtB,CAAA"}
+{"version":3,"file":"embed.types.d.ts","sourceRoot":"","sources":["../../src/generic/embed.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG;IACvC,IAAI,EAAE,MAAM,CAAA;CACf,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG;IACxC,KAAK,EAAE,MAAM,EAAE,CAAA;CAClB,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG;IAC1C,OAAO,EAAE,kBAAkB,CAAA;CAC9B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACtB,MAAM,EAAE,QAAQ,GAAG,MAAM,CAAC;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,UAAU,CAAC;CAC1B,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IACxC,MAAM,EAAE,MAAM,EAAE,CAAA;CACnB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG;IACzC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAA;CACtB,CAAA;AAED,MAAM,MAAM,kBAAkB,GAAG,eAAe,CAAA"}

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export * from './generic/embed.types.js';
 export * from './generic/baseEmbeddings.js';
 export * from './generic/baseAudio.js';
 export * from './generic/baseVideo.js';
+export * from './generic/baseRealtime.js';
+export * from './generic/baseRealtimeChannelServer.js';
 export * from './generic/errorTypes.js';
 export * from './generic/errorAnalyzer.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qCAAqC,CAAC;AACpD,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC"}

package/dist/index.js

@@ -11,6 +11,8 @@ export * from './generic/embed.types.js';
 export * from './generic/baseEmbeddings.js';
 export * from './generic/baseAudio.js';
 export * from './generic/baseVideo.js';
+export * from './generic/baseRealtime.js';
+export * from './generic/baseRealtimeChannelServer.js';
 export * from './generic/errorTypes.js';
 export * from './generic/errorAnalyzer.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAA;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,uBAAuB,CAAC;AACtC,cAAc,0BAA0B,CAAC;AACzC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,wBAAwB,CAAC;AACvC,cAAc,qCAAqC,CAAC;AACpD,cAAc,sBAAsB,CAAC;AACrC,cAAc,yBAAyB,CAAC"}