AbstractProtectedContextThe bound session context, available from Initialize until Dispose.
null outside that window — guard with ?. in any code that can run early/late.
AbstractChannelThe channel definition name — MUST match the MJ: AI Agent Channels row's Name
(e.g. 'Whiteboard'). The host routes OnChannelStateSave by the registry row's
name and warns when a resolved plugin's ChannelName disagrees with its row.
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 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).
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).
Executes ONE of this channel's server-side tools (a tool whose name starts with
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
GetServerToolDefinitions but forgets to implement execution fails safely and visibly.
The full tool name the model invoked (begins with ToolNamePrefix).
The raw arguments JSON string the model emitted for the call.
The execution result (or a structured error), synchronously or as a promise.
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 ToolNamePrefix so the host can route
its execution back here unambiguously.
Invoked by RealtimeChannelServerHost when assembling the session's tool set (after the
plugin's OnSessionStarted). Default: [] (a state-only channel contributes none).
The channel's server-executed tool definitions (possibly empty).
Media tracks this channel can SOURCE — samples flowing from the channel's surface INTO the
model. Default []: a channel contributes no media unless it says so.
This is where the media plane and the semantic plane meet. A channel remains a tool surface; declaring a sourced track additionally lets the model watch that surface live. The whiteboard sourcing inbound video is what lets an agent see what it draws and correct itself mid-stroke, and see what the user draws directly rather than through a described diff. The remote browser sourcing inbound video is what lets the model watch the page continuously while the agent still acts through tools — a different quality of control, not a faster version of polling screenshots.
Declared in CODE rather than metadata for the same reason GetServerToolDefinitions is:
whether a surface can produce frames is a property of the implementation, not a deployment
choice. Whether it should on a given session is negotiation
(ModelConfiguration.Realtime.RequestedTracks intersected with the model's support), and a
model with no video track simply falls back to the channel's tool-only behaviour.
Track descriptors this channel can produce (possibly empty).
Media tracks this channel can SINK — samples flowing from the model OUT to the channel's
surface. Default [].
Nothing in play emits non-audio outbound media yet; the contract admits it because direction is a property of a track rather than part of its type. An avatar is the obvious first case: a channel owning a render surface that sinks outbound video.
Track descriptors this channel can consume (possibly empty).
Binds the session context and invokes the OnInitialize hook. Called exactly once per session by the host, right after ClassFactory instantiation and before any lifecycle hook.
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.
The raw state-of-record payload the client submitted (already size-capped host-side).
The normalized payload to persist, or null to keep stateJson as-is.
ProtectedOnSubclass hook invoked from Initialize once Context is bound — allocate any per-session state here. Default: no-op.
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; Dispose follows after the host's brief post-close linger window (during which late state saves still route here first). Default: no-op.
The persisted close provenance, or null for legacy/unstamped rows.
Invoked by the host immediately after Initialize, when the durable session record has
been persisted (Status = 'Active') — the session id, agent, and conversation are all in
Context. Default: no-op.
Base class for SERVER-SIDE interactive-channel plugins (per
plans/ai-agent-sessions.md→ "Pluggable Interfaces (IAgentChannelServer&IAgentChannelClient)").Relationship to the plan's
IAgentChannelServerThe plan's interface anticipates server-bridged media — a channel that owns sockets, receives demultiplexed
OnClientMessagepayloads from a unifiedISessionTransport, 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 — whenISessionTransportlands, 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").Registration & resolution (mirrors the client half exactly)
Concrete plugins are
@RegisterClass(BaseRealtimeChannelServer, '<ServerPluginClass>')and are resolved at session start from the ACTIVEMJ: AI Agent Channelsrows: each row'sServerPluginClassis 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 aLoad<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→ Initialize(ctx) → OnSessionStarted → zero or more OnChannelStateSave calls (one per debounced client state-save landing on the server) → OnSessionClosed(reason) → 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 import('../..').BaseRealtimeChannelClient half). The two hooks:
[](a state-only channel like the whiteboard contributes no server tools).The per-session host (RealtimeChannelServerHost) aggregates every live plugin's GetServerToolDefinitions into the session's tool set (feeding
RealtimeSessionRunner.ServerChannelTools) and routes each{@link ToolNamePrefix}*tool call back to the owning plugin's ExecuteServerTool. Tool-name collisions across channels are avoided by each channel's ToolNamePrefix (mirroring the client half'sToolNamePrefix).Remarks
Socket/media members (
OnClientMessage,SendToClient) remain deferred with the unified-transport track — whenISessionTransportlands, this class grows an injected-transport overload rather than the plan's raw-socket form.