@memberjunction/ai-agents 5.40.2 → 5.42.0

package/dist/realtime/bridge-realtime-session-factory.js

@@ -0,0 +1,163 @@
+/**
+ * @fileoverview `CreateBridgeRealtimeSession` — the **provider-agnostic** server-side factory that turns an
+ * agent reference into a live {@link IRealtimeSession} for a Realtime Bridge. Given an agent id (or name)
+ * + a context user + a metadata provider, it:
+ *   1. resolves the `MJ: AI Agents` entity from the {@link AIEngine} cache,
+ *   2. instantiates the correct {@link BaseAgent} subclass via the `ClassFactory` (the same path
+ *      `AgentRunner` uses), and
+ *   3. calls {@link BaseAgent.StartBridgeRealtimeSession} to open the raw model session.
+ *
+ * This is the seam every bridge needs — `LiveKitAgentRoomCoordinator.SetSessionFactory`, and the
+ * (forthcoming) Teams/Zoom harnesses, all bind THIS one function. It deliberately lives in
+ * `@memberjunction/ai-agents` (which owns the agent + realtime-model lifecycle) and depends on NO bridge
+ * package, so a bridge package never has to reach back into the agent runtime — the consumer binds the
+ * factory at startup instead.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { BaseRealtimeModel, GetAIAPIKey } from '@memberjunction/ai';
+import { Metadata } from '@memberjunction/core';
+import { MJGlobal, UUIDsEqual } from '@memberjunction/global';
+import { AIEngine } from '@memberjunction/aiengine';
+import { BaseAgent } from '../base-agent.js';
+import { RealtimeClientSessionService } from './realtime-client-session-service.js';
+/**
+ * Opens a raw {@link IRealtimeSession} for the agent named in `ctx`. Bind this onto a bridge's
+ * session-factory seam (e.g. `LiveKitAgentRoomCoordinator.Instance.SetSessionFactory(CreateBridgeRealtimeSession)`).
+ *
+ * @param ctx The bridge session context (agent id/name + user + provider).
+ * @returns The live realtime session to hand to `AIBridgeEngine.StartBridgeSession`.
+ * @throws When the agent can't be resolved, has no DriverClass, the driver can't be instantiated, or no
+ *   usable Realtime model is configured (surfaced from {@link BaseAgent.StartBridgeRealtimeSession}).
+ */
+export async function CreateBridgeRealtimeSession(ctx) {
+    const provider = ctx.MetadataProvider ?? Metadata.Provider;
+    await AIEngine.Instance.Config(false, ctx.ContextUser, provider);
+    const agent = resolveAgentEntity(ctx);
+    if (!agent) {
+        throw new Error(`CreateBridgeRealtimeSession: no agent found for AgentID='${ctx.AgentID ?? ''}' / ` +
+            `AgentName='${ctx.AgentName ?? ''}'. Ensure the agent exists and the engine is configured.`);
+    }
+    // Instantiate the right BaseAgent subclass exactly as AgentRunner does (agent DriverClass, else its type's).
+    const agentType = AIEngine.Instance.AgentTypes.find((t) => UUIDsEqual(t.ID, agent.TypeID));
+    const driverClass = agent.DriverClass || agentType?.DriverClass;
+    if (!driverClass) {
+        throw new Error(`CreateBridgeRealtimeSession: agent '${agent.Name}' has no DriverClass (and its type none either).`);
+    }
+    const instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseAgent, driverClass);
+    if (!instance) {
+        throw new Error(`CreateBridgeRealtimeSession: ClassFactory could not create a BaseAgent for DriverClass '${driverClass}'.`);
+    }
+    return instance.StartBridgeRealtimeSession({
+        agent,
+        contextUser: ctx.ContextUser,
+        provider,
+        // A fresh bridge session starts with no prior turns; memory context degrades gracefully to empty.
+        conversationMessages: [],
+        // Realtime extras ride params.data: the TARGET agent the co-agent voices via `invoke-target-agent`
+        // (without it the co-agent stays idle), plus optional per-session dev overrides for the model/voice
+        // so two agents in the same room can sound distinct. Omitted keys are simply absent.
+        data: buildRealtimeData(ctx),
+    });
+}
+/**
+ * Builds the `params.data` bag from the bridge context — the realtime extras BaseAgent reads at session
+ * start. Returns `undefined` when nothing is set so the param stays cleanly absent.
+ */
+function buildRealtimeData(ctx) {
+    const data = {};
+    if (ctx.TargetAgentID) {
+        data.targetAgentID = ctx.TargetAgentID;
+    }
+    if (ctx.AgentSessionID && ctx.AgentSessionID.trim().length > 0) {
+        // Drives the co-agent observability run's session grouping (see WireBridgeRealtimeSession).
+        data.agentSessionId = ctx.AgentSessionID.trim();
+    }
+    if (ctx.RealtimeModelID && ctx.RealtimeModelID.trim().length > 0) {
+        data.realtimeModelID = ctx.RealtimeModelID.trim();
+    }
+    if (ctx.RealtimeVoice && ctx.RealtimeVoice.trim().length > 0) {
+        data.realtimeVoice = ctx.RealtimeVoice.trim();
+    }
+    if (ctx.MeetingMode === true) {
+        data.realtimeMeetingMode = true;
+    }
+    if (ctx.SelfNames && ctx.SelfNames.length > 0) {
+        data.realtimeSelfNames = ctx.SelfNames;
+    }
+    return Object.keys(data).length > 0 ? data : undefined;
+}
+/**
+ * The bridge-engine session-run finalizer (matches `BridgeSessionRunFinalizer` in
+ * `@memberjunction/ai-bridge-server`). Bind this onto `AIBridgeEngine.SetSessionRunFinalizer(...)` at
+ * startup so a bridge reaped WITHOUT a live session (a prior-boot orphan, a cross-host teardown) still
+ * finalizes its co-agent observability run — the only path where the `Close()`-wrapped finalizer can't run.
+ * Lives here (in ai-agents, which owns the realtime runtime) so the engine stays decoupled from it.
+ *
+ * @param agentSessionID The reaped session's id.
+ * @param success Whether to mark the run(s) `Completed` (true) or `Failed` (false).
+ * @param contextUser The user the writes run as (required — skipped without it).
+ * @param provider The metadata provider (required — skipped without it).
+ */
+export async function FinalizeBridgeCoAgentRuns(agentSessionID, success, contextUser, provider) {
+    if (!contextUser || !provider) {
+        return; // a server-side finalize needs a user + provider; a later reap with context catches it
+    }
+    await new RealtimeClientSessionService().FinalizeCoAgentRunsBySession(agentSessionID, success, contextUser, provider);
+}
+/**
+ * Enumerates the active Realtime models with each driver's supported voices — the source for the dev
+ * model/voice picker. Only models with an Active vendor + resolvable API key + ClassFactory driver are
+ * returned (a model you can't actually run isn't worth offering). Voices come from the driver
+ * ({@link BaseRealtimeModel.SupportedVoices}) — the near-term, driver-owned source of truth.
+ *
+ * @param contextUser The user the engine config runs as (server-side).
+ * @param provider The request-scoped metadata provider (multi-provider safe).
+ * @returns Active realtime models, each with its driver's voices.
+ */
+export async function GetRealtimeModelVoices(contextUser, provider) {
+    await AIEngine.Instance.Config(false, contextUser, provider);
+    const isRealtime = (t) => typeof t === 'string' && t.trim().toLowerCase() === 'realtime';
+    const models = AIEngine.Instance.Models
+        .filter((m) => m.IsActive && isRealtime(m.AIModelType))
+        .sort((a, b) => (b.PowerRank ?? 0) - (a.PowerRank ?? 0));
+    const out = [];
+    for (const model of models) {
+        const driverClass = resolveRealtimeDriverClass(model.ID);
+        if (!driverClass) {
+            continue; // no active vendor with a resolvable key — not runnable, so omit
+        }
+        const instance = MJGlobal.Instance.ClassFactory.CreateInstance(BaseRealtimeModel, driverClass, GetAIAPIKey(driverClass));
+        out.push({ ModelID: model.ID, ModelName: model.Name ?? '', Voices: instance?.SupportedVoices ?? [] });
+    }
+    return out;
+}
+/** The DriverClass of the highest-priority Active vendor (with a resolvable API key) for a model, or null. */
+function resolveRealtimeDriverClass(modelID) {
+    const vendors = AIEngine.Instance.ModelVendors
+        .filter((mv) => UUIDsEqual(mv.ModelID, modelID) && mv.Status === 'Active' && mv.DriverClass != null)
+        .sort((a, b) => (b.Priority ?? 0) - (a.Priority ?? 0));
+    for (const v of vendors) {
+        if (GetAIAPIKey(v.DriverClass)) {
+            return v.DriverClass;
+        }
+    }
+    return null;
+}
+/** Resolves the agent entity from the engine cache by id (preferred), then by case-insensitive name. */
+function resolveAgentEntity(ctx) {
+    const agents = AIEngine.Instance.Agents;
+    if (ctx.AgentID) {
+        const byId = agents.find((a) => UUIDsEqual(a.ID, ctx.AgentID));
+        if (byId) {
+            return byId;
+        }
+    }
+    if (ctx.AgentName) {
+        const wanted = ctx.AgentName.trim().toLowerCase();
+        return agents.find((a) => a.Name?.trim().toLowerCase() === wanted);
+    }
+    return undefined;
+}
+//# sourceMappingURL=bridge-realtime-session-factory.js.map

package/dist/realtime/bridge-realtime-session-factory.js.map

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

package/dist/realtime/bridge-room-transcript-sink.d.ts

@@ -0,0 +1,58 @@
+/**
+ * @fileoverview `CreateBridgeRoomTranscriptSink` — the app-layer implementation of the bridge engine's
+ * transcript sink. Persists a **unified per-room meeting transcript** into `MJ: Conversations` (one
+ * "Meeting Room" conversation per LiveKit room, keyed by the room's external id) + `MJ: Conversation Details`
+ * (one row per final utterance). The bridge engine elects ONE scribe per room and feeds its final transcript
+ * lines here, so the room records a single copy — not N (one per agent).
+ *
+ * Lives in `@memberjunction/ai-agents` (which owns the realtime/Conversations knowledge), NOT the bridge
+ * engine — the engine only emits neutral lines + the `(ConversationType, ApplicationScope, ...)` choices come
+ * from the binding site (the MJServer resolver), so nothing about "Meeting Room" or app scoping leaks into
+ * the generic engine. See `plans/realtime/realtime-session-lifecycle-and-followups.md` §5.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { IMetadataProvider, UserInfo } from '@memberjunction/core';
+/** The conversation `ApplicationScope` values (mirrors the entity union). `'Application'` hides it from the main chat list. */
+export type ConversationApplicationScope = 'Global' | 'Both' | 'Application';
+/** Options that shape the room conversation — supplied by the binding site so the engine stays generic. */
+export interface BridgeRoomTranscriptSinkOptions {
+    /** The `MJ: Conversations.Type` to stamp (e.g. `'Meeting Room'`) — the semantic label for room transcripts. */
+    ConversationType: string;
+    /** Scope of the room conversation. `'Application'` keeps it OUT of the normal chat list. Default `'Application'`. */
+    ApplicationScope?: ConversationApplicationScope;
+    /** Optional owning application id (e.g. the Meet app) so its surface can list its rooms. */
+    ApplicationID?: string;
+}
+/**
+ * One transcript line the engine emits (structurally matches `BridgeTranscriptLine` in
+ * `@memberjunction/ai-bridge-server`; mirrored here to avoid a package dependency, resolved structurally at
+ * the resolver binding site).
+ */
+export interface BridgeTranscriptLineInput {
+    /** The room grouping (driver external connection id) — one room = one unified transcript. */
+    RoomKey: string;
+    /** The scribe's agent-session id (attribution for its own speech). */
+    AgentSessionID: string;
+    /** The scribe's agent id, when known. */
+    AgentID?: string;
+    /** `true` for the scribe's OWN speech, `false` for anything it heard. */
+    IsAgentSpeech: boolean;
+    /** The speaker's participant id (the scribe's own bot id for its speech; absent for heard speech). */
+    SpeakerParticipantID?: string;
+    /** The final transcript text. */
+    Text: string;
+}
+/** The sink signature (matches the engine's `BridgeTranscriptSink`). */
+export type BridgeRoomTranscriptSink = (line: BridgeTranscriptLineInput, contextUser?: UserInfo, provider?: IMetadataProvider) => Promise<void>;
+/**
+ * Builds a {@link BridgeRoomTranscriptSink}. Bind the result onto `AIBridgeEngine.SetTranscriptSink(...)` at
+ * startup. Internally caches the room→conversation mapping (lazy get-or-create), dedupes concurrent creates
+ * per room, and serializes detail writes per conversation so transcript order is preserved.
+ *
+ * @param options The room-conversation shape (`Type`, scope, optional app id).
+ * @returns The sink function.
+ */
+export declare function CreateBridgeRoomTranscriptSink(options: BridgeRoomTranscriptSinkOptions): BridgeRoomTranscriptSink;
+//# sourceMappingURL=bridge-room-transcript-sink.d.ts.map

package/dist/realtime/bridge-room-transcript-sink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-room-transcript-sink.d.ts","sourceRoot":"","sources":["../../src/realtime/bridge-room-transcript-sink.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAgC,MAAM,sBAAsB,CAAC;AAGjG,+HAA+H;AAC/H,MAAM,MAAM,4BAA4B,GAAG,QAAQ,GAAG,MAAM,GAAG,aAAa,CAAC;AAE7E,2GAA2G;AAC3G,MAAM,WAAW,+BAA+B;IAC5C,+GAA+G;IAC/G,gBAAgB,EAAE,MAAM,CAAC;IACzB,qHAAqH;IACrH,gBAAgB,CAAC,EAAE,4BAA4B,CAAC;IAChD,4FAA4F;IAC5F,aAAa,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,yBAAyB;IACtC,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,aAAa,EAAE,OAAO,CAAC;IACvB,sGAAsG;IACtG,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,wEAAwE;AACxE,MAAM,MAAM,wBAAwB,GAAG,CACnC,IAAI,EAAE,yBAAyB,EAC/B,WAAW,CAAC,EAAE,QAAQ,EACtB,QAAQ,CAAC,EAAE,iBAAiB,KAC3B,OAAO,CAAC,IAAI,CAAC,CAAC;AAKnB;;;;;;;GAOG;AACH,wBAAgB,8BAA8B,CAAC,OAAO,EAAE,+BAA+B,GAAG,wBAAwB,CAsBjH"}

package/dist/realtime/bridge-room-transcript-sink.js

@@ -0,0 +1,127 @@
+/**
+ * @fileoverview `CreateBridgeRoomTranscriptSink` — the app-layer implementation of the bridge engine's
+ * transcript sink. Persists a **unified per-room meeting transcript** into `MJ: Conversations` (one
+ * "Meeting Room" conversation per LiveKit room, keyed by the room's external id) + `MJ: Conversation Details`
+ * (one row per final utterance). The bridge engine elects ONE scribe per room and feeds its final transcript
+ * lines here, so the room records a single copy — not N (one per agent).
+ *
+ * Lives in `@memberjunction/ai-agents` (which owns the realtime/Conversations knowledge), NOT the bridge
+ * engine — the engine only emits neutral lines + the `(ConversationType, ApplicationScope, ...)` choices come
+ * from the binding site (the MJServer resolver), so nothing about "Meeting Room" or app scoping leaks into
+ * the generic engine. See `plans/realtime/realtime-session-lifecycle-and-followups.md` §5.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { RunView, LogError, LogStatus } from '@memberjunction/core';
+const CONVERSATION_ENTITY = 'MJ: Conversations';
+const CONVERSATION_DETAIL_ENTITY = 'MJ: Conversation Details';
+/**
+ * Builds a {@link BridgeRoomTranscriptSink}. Bind the result onto `AIBridgeEngine.SetTranscriptSink(...)` at
+ * startup. Internally caches the room→conversation mapping (lazy get-or-create), dedupes concurrent creates
+ * per room, and serializes detail writes per conversation so transcript order is preserved.
+ *
+ * @param options The room-conversation shape (`Type`, scope, optional app id).
+ * @returns The sink function.
+ */
+export function CreateBridgeRoomTranscriptSink(options) {
+    const scope = options.ApplicationScope ?? 'Application';
+    /** roomKey(lower) → resolved ConversationID (populated once get-or-create settles). */
+    const roomToConversation = new Map();
+    /** roomKey(lower) → in-flight get-or-create promise (dedupes concurrent first lines for a room). */
+    const ensureInFlight = new Map();
+    /** ConversationID → serial write chain (preserves detail ordering, error-isolated). */
+    const writeChains = new Map();
+    return async (line, contextUser, provider) => {
+        if (!contextUser || !provider) {
+            return; // a server-side write needs a user + provider; nothing to do without them
+        }
+        const conversationID = await ensureRoomConversation(line.RoomKey, options.ConversationType, scope, options.ApplicationID, roomToConversation, ensureInFlight, contextUser, provider);
+        if (!conversationID) {
+            return;
+        }
+        const prior = writeChains.get(conversationID) ?? Promise.resolve();
+        const next = prior.then(() => writeTranscriptDetail(conversationID, line, contextUser, provider));
+        writeChains.set(conversationID, next.then(() => undefined, () => undefined));
+        await next;
+    };
+}
+/** Resolves (cache → existing row → create) the room's `MJ: Conversations` id, deduping concurrent creates. */
+async function ensureRoomConversation(roomKey, conversationType, scope, applicationID, cache, inFlight, contextUser, provider) {
+    const key = roomKey.trim().toLowerCase();
+    const cached = cache.get(key);
+    if (cached) {
+        return cached;
+    }
+    const pending = inFlight.get(key);
+    if (pending) {
+        return pending;
+    }
+    const task = resolveOrCreateConversation(roomKey, conversationType, scope, applicationID, contextUser, provider)
+        .then((id) => {
+        if (id) {
+            cache.set(key, id);
+        }
+        return id;
+    })
+        .finally(() => inFlight.delete(key));
+    inFlight.set(key, task);
+    return task;
+}
+/** Finds an existing non-archived room conversation by `ExternalID` + `Type`, else creates one. */
+async function resolveOrCreateConversation(roomKey, conversationType, scope, applicationID, contextUser, provider) {
+    const rv = new RunView();
+    const found = await rv.RunView({
+        EntityName: CONVERSATION_ENTITY,
+        ExtraFilter: `ExternalID='${escapeSql(roomKey)}' AND Type='${escapeSql(conversationType)}' AND (IsArchived IS NULL OR IsArchived=0)`,
+        Fields: ['ID'],
+        OrderBy: '__mj_CreatedAt DESC',
+        MaxRows: 1,
+        ResultType: 'simple',
+    }, contextUser);
+    if (found.Success && found.Results.length > 0) {
+        return found.Results[0].ID;
+    }
+    const conversation = await provider.GetEntityObject(CONVERSATION_ENTITY, contextUser);
+    conversation.NewRecord();
+    conversation.UserID = contextUser.ID;
+    conversation.Name = `Meeting Room ${roomKey}`;
+    conversation.Type = conversationType;
+    conversation.ExternalID = roomKey;
+    conversation.ApplicationScope = scope;
+    if (applicationID) {
+        conversation.ApplicationID = applicationID;
+    }
+    if (await conversation.Save()) {
+        LogStatus(`CreateBridgeRoomTranscriptSink: created '${conversationType}' conversation ${conversation.ID} for room ${roomKey}.`);
+        return conversation.ID;
+    }
+    LogError(`CreateBridgeRoomTranscriptSink: failed to create room conversation: ${conversation.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    return null;
+}
+/** Writes one `MJ: Conversation Details` row for a transcript line (Role mapped; agent speech attributed). */
+async function writeTranscriptDetail(conversationID, line, contextUser, provider) {
+    const detail = await provider.GetEntityObject(CONVERSATION_DETAIL_ENTITY, contextUser);
+    detail.NewRecord();
+    detail.ConversationID = conversationID;
+    // The scribe's own speech is the agent ('AI'); everything it heard (humans + other agents) is 'User'.
+    detail.Role = line.IsAgentSpeech ? 'AI' : 'User';
+    detail.Message = line.Text;
+    if (line.SpeakerParticipantID) {
+        detail.ExternalID = line.SpeakerParticipantID;
+    }
+    if (line.IsAgentSpeech) {
+        detail.AgentSessionID = line.AgentSessionID;
+        if (line.AgentID) {
+            detail.AgentID = line.AgentID;
+        }
+    }
+    if (!(await detail.Save())) {
+        LogError(`CreateBridgeRoomTranscriptSink: failed to write transcript detail: ${detail.LatestResult?.CompleteMessage ?? 'unknown error'}`);
+    }
+}
+/** Escapes single quotes for safe embedding in an `ExtraFilter` literal. */
+function escapeSql(value) {
+    return value.replace(/'/g, "''");
+}
+//# sourceMappingURL=bridge-room-transcript-sink.js.map

package/dist/realtime/bridge-room-transcript-sink.js.map

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

package/dist/realtime/meeting-controls-channel-server.d.ts

@@ -0,0 +1,198 @@
+/**
+ * @fileoverview The **Meeting Controls** server-side channel — a SERVER-ONLY interactive channel
+ * (no Angular client surface) that turns a realtime agent into a meeting **facilitator**.
+ *
+ * It contributes a facilitator tool vocabulary the agent invokes server-side (`RaiseHand`,
+ * `LowerHand`, `CallOnParticipant`, `MuteParticipant`, `SetTimer`) and feeds back the perception that
+ * makes facilitation possible: the ordered **hand-raise queue** (who raised, in order, how long
+ * they've waited), **who is speaking**, the **roster**, and the agenda **timer** (elapsed / remaining).
+ * With that intel an agent can call on people in order, enforce time, and move the agenda — all
+ * through one channel's tools + perception.
+ *
+ * The channel has **no platform code**: the signals (roster / speaking / hand-raise) arrive from an
+ * INJECTED {@link IMeetingControlsEventSource} that each bridge driver adapts from its native
+ * participant/event stream. The queue + timer logic is the pure, fully unit-testable
+ * {@link MeetingControlsState}. This is the §4b "bridge contributes a channel" pattern realized as an
+ * MJ channel: dynamic tool vocabulary + perception, routed through the same channel plane as the
+ * MJ-native whiteboard.
+ *
+ * @module @memberjunction/ai-agents
+ * @author MemberJunction.com
+ */
+import { BaseRealtimeChannelServer, RealtimeToolDefinition, ServerChannelToolResult } from '@memberjunction/ai';
+import { MeetingControlsState, MeetingControlsClock, MeetingParticipant } from './meeting-controls-state.js';
+/** The channel name — matches the (seedable) `MJ: AI Agent Channels` row's `Name`. */
+export declare const MEETING_CONTROLS_CHANNEL_NAME = "Meeting Controls";
+/**
+ * The shared name prefix of every Meeting Controls tool. The host routes any tool call beginning with
+ * this prefix back to this channel's {@link MeetingControlsChannelServer.ExecuteServerTool}.
+ */
+export declare const MEETING_CONTROLS_TOOL_PREFIX = "MeetingControls_";
+/**
+ * The capability the channel gates `MuteParticipant` on. The injected event source advertises which
+ * facilitator actions the platform supports; muting is the only gated one (raising/lowering a hand,
+ * calling on, and timers are channel-internal and always available).
+ */
+export type MeetingControlsCapability = 'Mute';
+/**
+ * The signaling/perception + action surface a bridge driver supplies to the Meeting Controls channel.
+ *
+ * The channel SUBSCRIBES to the three perception streams and the channel maps the agent's tool calls
+ * back onto {@link MuteParticipant} (the one action that must reach the platform). Everything else
+ * (the queue, the timer, who is speaking) is maintained inside {@link MeetingControlsState} from these
+ * streams. Each bridge driver implements this by adapting its native participant/event stream — the
+ * channel itself never names a platform.
+ *
+ * All `On*` registrations are "latest handler wins" (one channel instance per session).
+ */
+export interface IMeetingControlsEventSource {
+    /**
+     * Registers a handler for roster changes. The channel rebuilds its roster from each snapshot and
+     * prunes departed participants from the queue / speaking / mute state.
+     *
+     * @param handler Invoked with the full current roster on every change.
+     */
+    OnRosterChange(handler: (participants: MeetingParticipant[]) => void): void;
+    /**
+     * Registers a handler for diarized speaking changes — the set of participant ids currently
+     * speaking.
+     *
+     * @param handler Invoked with the speaking participant ids on every change.
+     */
+    OnSpeakingChange(handler: (participantIds: string[]) => void): void;
+    /**
+     * Registers a handler for hand-raise/lower signals the PLATFORM surfaces (e.g. a participant uses
+     * Zoom's native "raise hand"). `raised = true` enqueues, `false` dequeues — mirroring the agent's
+     * own `RaiseHand`/`LowerHand` tools so platform-raised and agent-raised hands share one queue.
+     *
+     * @param handler Invoked with the participant id and whether the hand is now raised.
+     */
+    OnHandRaiseChange(handler: (participantId: string, raised: boolean) => void): void;
+    /**
+     * Mutes a participant on the platform (the actuation behind the agent's `MuteParticipant` tool).
+     * Capability-gated by {@link Capabilities}; the channel checks the capability before calling this.
+     *
+     * @param participantId The participant to mute.
+     * @returns A promise resolving once the mute request has been issued.
+     */
+    MuteParticipant(participantId: string): Promise<void>;
+    /**
+     * The facilitator capabilities this platform supports (e.g. `['Mute']`). The channel gates the
+     * `MuteParticipant` tool on `'Mute'` being present; absent capabilities make the corresponding
+     * tool return a structured "not supported" result instead of calling the source.
+     */
+    readonly Capabilities: ReadonlyArray<MeetingControlsCapability>;
+}
+/**
+ * Dependencies injected into a {@link MeetingControlsChannelServer} — the platform event source and an
+ * optional deterministic clock. Injected (rather than resolved) so the channel is fully unit-testable
+ * with a fake source and a controllable clock, and so the platform wiring is the driver's concern.
+ */
+export interface MeetingControlsChannelDeps {
+    /** The bridge-supplied perception/action surface. */
+    EventSource: IMeetingControlsEventSource;
+    /** Optional clock for the queue/timer math (defaults to `Date.now`). */
+    Clock?: MeetingControlsClock;
+}
+/**
+ * Server-only Meeting Controls channel — the facilitator surface. ONE instance per session.
+ *
+ * Unlike the whiteboard (resolved from the registry by the host via a parameterless ClassFactory
+ * construction), this channel needs a per-session {@link IMeetingControlsEventSource} from the bridge,
+ * so a bridge driver constructs it directly with {@link MeetingControlsChannelDeps} and hands it to
+ * the host's per-session plugin set. It has **no client surface** — the contract's
+ * `GetServerToolDefinitions` / `ExecuteServerTool` are the entire interface; there is no
+ * `GetSurfaceComponent` on the server half at all.
+ *
+ * Registered under {@link MEETING_CONTROLS_CHANNEL_NAME} so a seeded registry row can resolve a
+ * default (event-source-less) instance for discovery; a real session always injects the driver's
+ * event source.
+ */
+export declare class MeetingControlsChannelServer extends BaseRealtimeChannelServer {
+    /** The pure facilitator state (queue / speaking / roster / mute / timer). */
+    private readonly state;
+    /** The injected platform event source, or `null` for a registry-resolved discovery instance. */
+    private readonly eventSource;
+    /**
+     * @param deps Optional per-session dependencies. Omitted only for a registry-resolved discovery
+     *   instance (the host's ClassFactory path) — such an instance maintains no live state and
+     *   contributes its tool vocabulary but cannot actuate platform mutes.
+     */
+    constructor(deps?: MeetingControlsChannelDeps);
+    /** @inheritdoc */
+    get ChannelName(): string;
+    /** @inheritdoc */
+    get ToolNamePrefix(): string;
+    /** Read-only access to the live facilitator state (for the channel's own perception + tests). */
+    get State(): MeetingControlsState;
+    /**
+     * Subscribes the injected event source's perception streams into {@link MeetingControlsState} and
+     * emits an initial perception snapshot. A discovery instance (no event source) is inert.
+     */
+    OnSessionStarted(): Promise<void>;
+    /**
+     * The facilitator tool vocabulary. `MuteParticipant` is included only when the platform advertises
+     * the `'Mute'` capability — so the contributed tool set is **runtime-computed** from the connected
+     * platform's abilities (the §4b dynamic-tool point), not a fixed constant.
+     *
+     * @returns The contributed server-executed tool definitions.
+     */
+    GetServerToolDefinitions(): RealtimeToolDefinition[];
+    /**
+     * Executes one facilitator tool and returns the result (the model narrates it). Tool dispatch is
+     * by the bare tool name (after the {@link MEETING_CONTROLS_TOOL_PREFIX}). Never throws — bad args
+     * or an unknown tool resolve to a structured failure result.
+     *
+     * @param toolName The full tool name (prefixed).
+     * @param argsJson The raw arguments JSON.
+     * @returns The execution result.
+     */
+    ExecuteServerTool(toolName: string, argsJson: string): Promise<ServerChannelToolResult>;
+    /** `RaiseHand(participantId)` — enqueue a participant; emits perception on a real change. */
+    private execRaiseHand;
+    /** `LowerHand(participantId)` — dequeue a participant. */
+    private execLowerHand;
+    /** `CallOnParticipant(participantId?)` — call on a specific person or the front of the queue. */
+    private execCallOn;
+    /** `MuteParticipant(participantId)` — capability-gated; actuates the platform mute. */
+    private execMute;
+    /** `SetTimer(seconds)` — start/clear the agenda timer. */
+    private execSetTimer;
+    /**
+     * Serializes the current facilitator state and feeds it to the model as a background context note
+     * (no spoken reply forced). No-op when the host context supplies no perception sink (provider
+     * can't inject mid-session, or no live session yet).
+     *
+     * @param reason A short label for the change that triggered the perception (logging only).
+     */
+    private emitPerception;
+    /** Whether the platform advertises mute support. */
+    private muteSupported;
+    /** Builds one tool definition with the prefixed name. */
+    private tool;
+    /** JSON schema for a `{ participantId }` tool; `required` controls whether the id is mandatory. */
+    private participantSchema;
+    /** JSON schema for the `SetTimer` tool. */
+    private setTimerSchema;
+    /** Parses a participant-targeting tool's args, tolerating malformed JSON. */
+    private parseParticipantArgs;
+    /** Parses the `SetTimer` tool's args, tolerating malformed JSON. */
+    private parseSetTimerArgs;
+    /** Returns the required `participantId` or `null` when absent/blank. */
+    private requireParticipantId;
+    /** A standard "missing participantId" failure result for a tool. */
+    private missingParticipant;
+    /** A participant's display name, falling back to their id. */
+    private name;
+    /** 1-based queue position of a participant (0 when not queued). */
+    private queuePosition;
+    /** Parses JSON into `T`, returning an empty object on any error (channels never throw on bad args). */
+    private safeParse;
+}
+/**
+ * Tree-shaking prevention for {@link MeetingControlsChannelServer}'s `@RegisterClass` registration.
+ * Call from a static code path so the registration is never eliminated by the bundler — mirroring
+ * every other `Load…()` in the realtime stack.
+ */
+export declare function LoadMeetingControlsChannelServer(): void;
+//# sourceMappingURL=meeting-controls-channel-server.d.ts.map

package/dist/realtime/meeting-controls-channel-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meeting-controls-channel-server.d.ts","sourceRoot":"","sources":["../../src/realtime/meeting-controls-channel-server.ts"],"names":[],"mappings":"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"}