AbstractThe 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 BindSurface without casts.
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 BindSurface without casts.
ProtectedContextThe host context, available from Initialize until Dispose.
null outside that window — guard with ?. in any code that can run early/late.
ProtectedSessionProtectedSessionMax time 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).
AbstractChannelThe channel definition name — MUST match the MJ: AI Agent Channels row's Name
(e.g. 'Whiteboard'). Used as the persistence key for SerializeState saves
and as the channel tab's stable key.
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 ChannelName so every channel still reads as a distinct, colored
surface. A channel only overrides this to enforce a specific brand accent.
AbstractTabFont Awesome icon class for the channel's tab (e.g. 'fa-solid fa-chalkboard').
AbstractTabLabel for the channel's tab on the overlay's surface panel (e.g. 'Whiteboard').
AbstractToolThe shared name prefix of every tool this channel exposes (e.g. 'Whiteboard_').
The host registers ONE local-execution route per plugin: tool calls whose name starts
with this prefix go to ApplyAgentTool instead of the server relay.
AbstractApplyExecutes ONE agent tool call locally (the ACTION direction) and returns the result
JSON string fed back to the model as the tool_response. Called for every tool whose
name starts with ToolNamePrefix. Must work both WITH a bound surface (apply +
UI garnish) and WITHOUT one (apply to the state engine directly — the tab pane may not
exist, e.g. the surface panel is collapsed). Should not throw: return a
{ success: false, error } payload so the model can narrate the failure (the host
additionally wraps anything thrown).
AbstractBindCalled by the host right after it created the surface component (and BEFORE the
component's first change detection, so inputs set here are visible in its ngOnInit).
The plugin — which knows its own component type — sets inputs (state engine, agent
name, …) and subscribes outputs here, wiring perception/garnish flows back through
Context. May be called again with a NEW instance after an
UnbindSurface (the pane is destroyed/recreated with the tab panel).
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 RealtimeChannelContext.RequestSave pipeline) before disposal.
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 ChannelOnboardingDetails. A plugin that
doesn't override it simply shows nothing — onboarding is strictly opt-in.
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
BindSurface/UnbindSurface — but the channel's tools (GetToolDefinitions /
ApplyAgentTool) and perception (RealtimeChannelContext.SendContextNote) still run.
A created surface instance is handed straight back via BindSurface; the host treats it as
opaque.
Default: null (server-only). A channel with a rendered surface overrides this to return its
component type.
AbstractGetThe channel's CLIENT-EXECUTED tool declarations, aggregated by the session service
into the clientTools set declared to the realtime model at session mint. The server
only DECLARES these — execution stays in the browser via ApplyAgentTool.
Whether this channel has a rendered MJ surface (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 GetSurfaceComponent once).
Binds the host context and invokes the OnInitialize hook. Called exactly once per session, right after ClassFactory instantiation and before any tool call or surface bind.
ProtectedOnSubclass hook invoked from Initialize once Context is bound — wire
state-engine subscriptions (e.g. state change → Context.RequestSave(...)) here.
Default: no-op.
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.
ProtectedResolveResolves the live 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 SessionIdWaitTimeoutMs — or the channel was
Disposed in the meantime (Context goes null, so we stop waiting on a torn-down session).
Restores a PRIOR session's saved channel state (the payload a previous session persisted via SerializeState / RealtimeChannelContext.RequestSave). Invoked by the session host AFTER 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.
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.
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, ApplyAgentTool runs in its no-surface mode. Default: no-op.
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:
{@link ToolNamePrefix}*calls to — the ACTION direction;nullfrom GetSurfaceComponent (HasSurface isfalse) and the overlay simply skips its tab while still wiring its tools + perception;Registration & resolution (mirrors the realtime model drivers)
Concrete plugins are
@RegisterClass(BaseRealtimeChannelClient, '<ClientPluginClass>')and are resolved at session start from theMJ: AI Agent Channelsregistry: each ACTIVE row'sClientPluginClassis the ClassFactory key (exactly howBaseRealtimeClientdrivers resolve by provider key). Ship aLoad<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→ Initialize(ctx) → zero or more BindSurface/UnbindSurface cycles (the surface pane is created/destroyed with the overlay's tab panel, e.g. collapse/expand) → Dispose at teardown. 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.