Skip to content

@memberjunction/ng-conversations

A comprehensive Angular component library for building conversation-based interfaces in MemberJunction, including messaging, artifact management, collections, projects, tasks, agent interaction panels, and collaboration features.

Layering note. The orchestration logic (agent dispatch, default-agent resolution, mention parsing, bridge state, streaming, client tools, sessions observability) lives in @memberjunction/conversations-runtime — a pure-TS, framework-agnostic package. This widget is one consumer of the runtime; React/Vue/Node hosts are also intended consumers. The widget is automatically wired to the runtime via ConversationsRuntimeBootstrap (registered providedIn: 'root'), which injects adapters for notifications, active-task tracking, and realtime sessions. See guides/CONVERSATIONS_UX_STACK_GUIDE.md for the full architecture.

The widget exposes three layers of extension:

SurfaceWhat it lets you do
6 named slots (mjChatSlot directive)Replace the header, emptyState, agentPresence, messageRenderer, messageExtra, or demonstrationSurface regions with your own templates. Three consumption modes: project an ad-hoc template, wrap the exported default for containment, or subclass the default.
Before/After cancelable events(beforeAgentTurn), (beforeToolInvoked), (beforeResponseFormSubmitted) let you observe AND veto (event.Cancel = true) before the action runs. Plus informational (sessionStarted) / (sessionChannelStateChanged) / (sessionEnded) for realtime lifecycle.
--mj-chat-* design tokensOverride bubble colors, composer chrome, character accents, and voice-state hues via standard CSS custom-property overrides. Defaults adapt to dark mode through semantic --mj-* tokens.

Slot interfaces + cloneable default components + the ChatSlotDirective are exported — see the public API.

The @memberjunction/ng-conversations package is a large, feature-rich module that powers MemberJunction’s conversation UI. It provides 40+ components covering the entire conversation lifecycle: message composition and rendering (with markdown, mentions, code blocks, and artifacts), conversation navigation and history, threaded discussions, artifact collections and libraries, project/task management, agent execution panels, sharing/permission modals, search, notifications, and export.

graph TD
    A[ConversationsModule] --> B[Messaging]
    A --> C[Navigation]
    A --> D[Collections & Library]
    A --> E[Agent & Tasks]
    A --> F[Collaboration]

    B --> B1[MessageItemComponent]
    B --> B2[MessageListComponent]
    B --> B3[MessageInputComponent]
    B --> B4[MentionEditorComponent]
    B --> B5[SuggestedResponsesComponent]
    B --> B6[ConversationMessageRatingComponent]

    C --> C1[ConversationWorkspaceComponent]
    C --> C2[ConversationNavigationComponent]
    C --> C3[ConversationSidebarComponent]
    C --> C4[ConversationListComponent]
    C --> C5[ConversationChatAreaComponent]
    C --> C6[ThreadPanelComponent]

    D --> D1[CollectionTreeComponent]
    D --> D2[CollectionViewComponent]
    D --> D3[LibraryFullViewComponent]
    D --> D4[ArtifactCreateModalComponent]

    E --> E1[AgentProcessPanelComponent]
    E --> E2[ActiveAgentIndicatorComponent]
    E --> E3[TasksFullViewComponent]
    E --> E4[GlobalTasksPanelComponent]

    F --> F1[ShareModalComponent]
    F --> F2[MembersModalComponent]
    F --> F3[ExportModalComponent]
    F --> F4[SearchPanelComponent]

    style A fill:#2d6a9f,stroke:#1a4971,color:#fff
    style B fill:#7c5295,stroke:#563a6b,color:#fff
    style C fill:#2d8659,stroke:#1a5c3a,color:#fff
    style D fill:#b8762f,stroke:#8a5722,color:#fff
    style E fill:#7c5295,stroke:#563a6b,color:#fff
    style F fill:#2d8659,stroke:#1a5c3a,color:#fff
Terminal window
npm install @memberjunction/ng-conversations
import { ConversationsModule } from '@memberjunction/ng-conversations';
@NgModule({
imports: [ConversationsModule]
})
export class YourModule { }

The top-level workspace component provides a complete conversation experience with sidebar, chat area, and thread panel:

<mj-conversation-workspace
[conversationId]="selectedConversationId"
(conversationChanged)="onConversationChanged($event)">
</mj-conversation-workspace>

The chat area handles message display, input, and agent interactions:

<mj-conversation-chat-area
[conversationId]="conversationId"
[conversation]="conversation"
[threadId]="selectedThreadId"
[isNewConversation]="isNewConversation"
(conversationCreated)="onConversationCreated($event)"
(threadOpened)="onThreadOpened($event)"
(threadClosed)="onThreadClosed()">
</mj-conversation-chat-area>

Embedding products (white-labeled end-user apps, embedded widgets) can pare the chat surface down through the component contract — no CSS overrides on internal class names. All default to true, so existing consumers are unaffected. Set to false to remove the feature entirely (the affordance is not rendered, not merely disabled):

InputGates
allowMentions@-mention support in the composer
allowAttachmentsThe file-attachment button
allowPlanModeThe composer’s Plan Mode toggle button
allowRealtimeThe composer’s real-time voice (co-agent) launcher button
showEmptyFillThe message list’s built-in “No messages yet” filler
showLoadingStateThe centered loading spinner (loading still short-circuits rendering, so hiding it does not flash the empty state)
showAgentPickerThe agent picker
showAgentModePickerThe agent-mode picker
showExportButtonThe conversation export button
showShareButtonThe conversation share button
showArtifactIndicatorThe artifact indicator
showAgentRunDetailsThe per-message agent run-detail grid (run ID, step/token counts, $ cost) — developer/observability data most end-user surfaces hide
showReactionsThe per-message reaction buttons (like / comment)
showMessageRatingThe per-message thumbs rating control
allowPinningMessage pinning (per-message pin button, header pin chip, pinned-messages panel)
allowMessageEditThe per-message edit button (owner’s own messages)
allowMessageDeleteThe per-message delete button (owner’s own messages)
showSuggestedPromptsThe empty-state’s built-in suggested-prompt chips
showDateNavigationThe message list’s sticky date header + jump-to-date navigation
<!-- e.g. a minimal, single-agent end-user surface -->
<mj-conversation-chat-area
[conversationId]="conversationId"
[allowPlanMode]="false"
[allowRealtime]="false"
[showEmptyFill]="false"
[showAgentPicker]="false">
</mj-conversation-chat-area>

A floating chat panel (bottom-right corner) that wraps the chat area for persistent agent access across the application. Collapses to a bubble icon, expands to a full chat panel.

<mj-chat-agents-overlay
[IsVisible]="!isChatRoute"
(ToolExecuted)="onToolExecuted($event)"
(OpenEntityRecord)="onOpenRecord($event)"
(OpenFullWorkspace)="onExpandToWorkspace($event)">
</mj-chat-agents-overlay>

The overlay is generic — it raises events for navigation and tool execution. The consuming application (e.g., MJExplorer) handles those events with app-specific logic like NavigationService.OpenEntityRecord().

Related packages:

<mj-message-list
[messages]="conversationMessages"
[isLoading]="isLoadingMessages"
(messageRated)="onMessageRated($event)">
</mj-message-list>
<mj-message-input
[conversationId]="conversationId"
[allowSend]="!isProcessing"
(messageSent)="onMessageSent($event)">
</mj-message-input>
<mj-mention-editor
[mentionSources]="availableMentionSources"
(mentionSelected)="onMentionSelected($event)">
</mj-mention-editor>
<!-- Collection tree for organizing artifacts -->
<mj-collection-tree
[projectId]="currentProjectId"
(collectionSelected)="onCollectionSelected($event)">
</mj-collection-tree>
<!-- Full library view -->
<mj-library-full-view
[projectId]="currentProjectId">
</mj-library-full-view>
<!-- Project selector -->
<mj-project-selector
[currentProjectId]="projectId"
(projectChanged)="onProjectChanged($event)">
</mj-project-selector>
<!-- Tasks view -->
<mj-tasks-full-view
[projectId]="currentProjectId">
</mj-tasks-full-view>
<!-- Agent execution panel -->
<mj-agent-process-panel
[agentRunId]="activeRunId">
</mj-agent-process-panel>
<!-- Active agent indicator -->
<mj-active-agent-indicator
[isActive]="agentIsRunning">
</mj-active-agent-indicator>

The package hosts the full client UX for MJ’s real-time co-agent sessions — live voice calls with the conversation’s agent, with interactive channel surfaces (the live Whiteboard) docked beside the call. Architecture background: guides/REALTIME_CO_AGENTS_GUIDE.md.

RealtimeSessionService (services/realtime-session.service.ts) is the provider-agnostic orchestrator, injectable at root. It drives a client-direct session: it calls the StartRealtimeClientSession mutation to mint a server-scoped ephemeral credential, resolves the matching BaseRealtimeClient driver (from @memberjunction/ai-realtime-client — OpenAI, Gemini, ElevenLabs, or AssemblyAI) through the ClassFactory by the server-reported Provider key, and connects the browser directly to the realtime provider — audio frames never transit the MJ server; only tool calls, final transcripts, channel state, and usage telemetry relay back over GraphQL. It exposes the reactive session state hosts consume: ConnectionState$ (connecting | listening | speaking | thinking | error | closed), Captions$, Active$, DelegationProgress$ / DelegationResult$ / DelegationNarration$, ActiveChannels$, ChannelFocus$, Minimized$, plus SendText (typed input into the live call), ToggleMute, RegisterClientToolHandler (prefix-routed, client-executed UI tools), and the explicit delegation cancel channel — CancelDelegation(callId) / CancelInFlightDelegations() call the CancelRealtimeSessionTool mutation and flip the card to “Cancelled by user” (deliberate policy: true barge-in never aborts delegated work — only the per-card ✕ does). The client driver’s OnUsage token deltas are accumulated and relayed onto the co-agent’s observability prompt run via RelayRealtimeUsage, debounced (10 s) plus a teardown flush.

Co-agent selection, pairing constraints & authorization-gated overrides: the composer’s voice picker (mj-voice-agent-picker, opened by the caret next to the phone button — or automatically on a conversation with no prior agent participation) lets every user choose which co-agent (ACTIVE Realtime-type agent, from the same run-permission-filtered cache the @mention routing uses) fronts the call when more than one exists; the choice rides the mint’s coAgentId and persists cross-device via UserInfoEngine (mj.realtimeVoice.coAgent.v1), so the friction-free instant start honors it too. A co-agent with rows in MJ: AI Agent Paired Agents may only front its paired targets — the picker constrains the target list to those rows (Sequence order, IsDefault preselected; pure helpers in services/voice-pairing.ts) — while a co-agent with zero rows stays universal (today’s flow untouched; pairings constrain a chosen co-agent, they never mandate one). The voice-model selector (and any future session-config override, carried as the mint’s configOverridesJson, e.g. {"realtime":{"modelPreference":…}}) renders only for users holding the Realtime: Advanced Session Controls MJ Authorization — evaluated client-side by the pure UserHoldsAuthorization helper (services/user-authorization.ts) from cached metadata as a disclosure gate; the server independently enforces the authorization on the mint, and unauthorized users silently get server defaults. (The gear popover’s interface-density control is UX disclosure, not session config — it is not gated.)

The call overlay (components/realtime/): RealtimeSessionOverlayComponent (mj-realtime-session-overlay) fills the conversation panel in place while a session is active — hosted by ConversationChatAreaComponent behind Active$, started from the mic button in MessageInputComponent. Two columns:

  • Main column — the unified APP-BAR (RealtimeAgentBannerComponent: identity + turn state + model name + the disclosure-gated action cluster — captions, the gear popover hosting the interface-density escape hatch and developer links, minimize, End call; in review the Start-live + Close actions live here too), then the pure-audio hero orb OR the unified session thread (RealtimeSessionThreadComponent, fed by the shared RealtimeSessionState merge of caption/delegation/narration streams), the channel strip, and the bottom dock (RealtimeComposerComponent: phone-call strip at low disclosure levels ⇄ fused mute/captions minis + typed composer at level 2+; typed turns behave identically to spoken ones).
  • Right panelRealtimeSurfaceTabsComponent, the tabbed surface panel (RealtimeSurfaceTabsModel is the framework-free, unit-tested tab state): channel tabs lead the strip, then one tab per artifact a delegated run produces (added UNFOCUSED with a persistent violet “unseen” glow until visited — content never steals the screen), with the Activity rail pinned LAST.

Progressive disclosure (realtime-disclosure.ts): the console grows with the user. A first-ever call is PURE AUDIO — a breathing hero orb, mute / Details / End, nothing to read; the caption thread, composer dock, surface panel and gear unlock by level (0–4) as the user acts (the hero’s “Show the conversation”, the T-to-type hotkey, the Details peek) or across sessions via the per-user milestones ratchet (UserInfoEngine, mj.realtimeVoice.uxMilestones.v1; the gear’s Simple/Standard/Pro/Auto density control is the manual escape hatch). Content never flips the console open — the one auto-reveal is a channel’s first agent activity (RealtimeSessionService.ChannelActivity$): the panel opens as a peek with that channel’s tab focused + flashed, while the left column stays exactly as it was. Review mode bypasses disclosure entirely.

Audio-reactive visuals (realtime-audio-visuals.ts): when the active driver meters its audio planes (BaseRealtimeClient.GetAudioActivity() — all four current drivers do, both directions), the overlay samples it on a requestAnimationFrame loop outside Angular and writes CSS variables directly: the hero orb scales with the smoothed output envelope (speaker-cone attack/decay), the EQ bars render the true 9-bin spectrum, and the visuals recolor by speaking direction (agent = brand, user = green) with hysteresis so syllable gaps never flicker. Un-metered drivers gracefully keep the turn-state-driven animations. See the guide’s §11 for the full pipeline.

Interactive channels are plugins — the shell is channel-agnostic. BaseRealtimeChannelClient (components/realtime/channels/base-realtime-channel-client.ts) is the contract: a client-executed tool set declared to the realtime model at session mint, a perception serializer feeding coalesced state deltas into the model as context notes, a dynamically-created Angular surface component the plugin binds itself, a persisted state of record, prior-session restore (RestoreState), artifact snapshots (SaveAsArtifact), and focus-mode layout requests. Plugins resolve at session start from the MJ: AI Agent Channels registry by ClientPluginClass key.

The live Whiteboard is a thin consumer of @memberjunction/ng-whiteboard — the board itself (the WhiteboardState engine, the Whiteboard_* tool API, the host/board/toolbar/zoom/popover/snapshot components, exports, the sandboxed-HTML-widget input bridge, the context menu) lives in that generic package; read its README for whiteboard details. This package contributes only the integration glue (components/realtime/whiteboard/): RealtimeWhiteboardChannel, the ~200-line channel plugin that declares WHITEBOARD_TOOL_DEFINITIONS to the model, routes Whiteboard_* calls to the bound host (or the pure engine call when the pane is collapsed), pipes the coalesced SceneDelta stream into the model as [whiteboard] context notes (with do-not-narrate-minor-edits etiquette inline), forwards widget submissions (MJWhiteboard.submit — the tutoring loop) and agent-undo events, persists/restores the board as the channel’s state of record, and snapshots it to versioned MJ: Artifacts; plus WhiteboardArtifactViewerPlugin (mj-whiteboard-artifact-viewer), the saved-board artifact viewer rendered through the package’s read-only snapshot component.

Session review & resume carryover: a past session replays through the same overlay in review mode — ConversationChatAreaComponent.OpenRealtimeSessionReview(agentSessionId) loads a RealtimeSessionReview via RealtimeSessionReviewService. The loader is chain-aware: a session resumed via lastSessionId chains legs, and the loader walks the chain backwards (capped, cycle-guarded), rendering every leg chronologically with a divider between legs that carries the previous leg’s CloseReason as a chip; the chain’s conversation-history artifacts load as unfocused artifact tabs, and a read-only Whiteboard tab appears when a board was saved. “Start live session” resumes as a new session chained via lastSessionId — saved channel states restore and the prior legs’ transcript is hydrated into the new model’s prompt server-side. The conversations resource also accepts a realtimeSessionId query param (the deep link the custom MJ: AI Agent Sessions form emits) and opens review mode directly.

This package never navigates (no Router): developer links emit a RealtimeNavigateRequest the host converts onto its openEntityRecord chain, and minimizing the call shows the host’s floating “on call” pill while the session stays live.

<!-- Share modal -->
<mj-share-modal
[visible]="showShareModal"
[resourceId]="resourceId"
[resourceType]="'conversation'"
(closed)="onShareClosed()">
</mj-share-modal>
<!-- Export modal -->
<mj-export-modal
[visible]="showExportModal"
[conversationId]="conversationId"
(exported)="onExported($event)">
</mj-export-modal>
ComponentSelectorDescription
MessageItemComponentmj-message-itemSingle message display with markdown, artifacts, and rating
MessageListComponentmj-message-listScrollable message list with auto-scroll
MessageInputComponentmj-message-inputMessage input with attachment support
MessageInputBoxComponentmj-message-input-boxCore input box with auto-resize
SuggestedResponsesComponentmj-suggested-responsesQuick response buttons
FormQuestionComponentmj-form-questionStructured form input within conversations
AgentResponseFormComponentmj-agent-response-formAgent-generated form responses
ActionableCommandsComponentmj-actionable-commandsClickable command suggestions
MentionDropdownComponentmj-mention-dropdown@-mention autocomplete dropdown
MentionEditorComponentmj-mention-editorRich text input with mention support
ConversationMessageRatingComponentmj-conversation-message-ratingMessage feedback (thumbs up/down)
ComponentSelectorDescription
ConversationWorkspaceComponentmj-conversation-workspaceFull workspace layout
ConversationNavigationComponentmj-conversation-navigationTop-level navigation
ConversationSidebarComponentmj-conversation-sidebarLeft sidebar with conversation list
ConversationListComponentmj-conversation-listScrollable conversation history
ConversationChatAreaComponentmj-conversation-chat-areaMain chat area
ConversationEmptyStateComponentmj-conversation-empty-stateEmpty state display
ThreadPanelComponentmj-thread-panelThreaded discussion panel
ComponentSelectorDescription
CollectionTreeComponentmj-collection-treeHierarchical collection browser
CollectionViewComponentmj-collection-viewCollection detail view
CollectionArtifactCardComponentmj-collection-artifact-cardArtifact card within collections
LibraryFullViewComponentmj-library-full-viewFull library interface
CollectionFormModalComponentmj-collection-form-modalCreate/edit collection
ArtifactCreateModalComponentmj-artifact-create-modalCreate new artifact
CollectionsFullViewComponentmj-collections-full-viewAll collections browser
ComponentSelectorDescription
ProjectSelectorComponentmj-project-selectorProject selection dropdown
ProjectFormModalComponentmj-project-form-modalCreate/edit project
TasksFullViewComponentmj-tasks-full-viewFull tasks management view (standalone)
TasksDropdownComponentmj-tasks-dropdownTask quick-access dropdown
TaskWidgetComponentmj-task-widgetCompact task widget
GlobalTasksPanelComponentmj-global-tasks-panelGlobal tasks panel
ComponentSelectorDescription
AgentProcessPanelComponentmj-agent-process-panelAgent execution panel
ActiveAgentIndicatorComponentmj-active-agent-indicatorActive processing indicator
ActiveTasksPanelComponentmj-active-tasks-panelActive tasks panel
ComponentSelectorDescription
RealtimeSessionOverlayComponentmj-realtime-session-overlayThe in-place “call mode” overlay for a live voice session (progressive-disclosure console: pure-audio hero → full two-column; audio-reactive orb/EQ)
RealtimeAgentBannerComponentmj-realtime-agent-bannerThe unified app-bar: identity + turn-state + disclosure-gated actions (captions, gear popover w/ density + dev links, minimize, End; review Start-live + Close)
RealtimeSessionThreadComponentmj-realtime-session-threadUnified live thread (captions, delegation cards, ephemeral narration)
RealtimeActivityRailComponentmj-realtime-activity-railSession activity rail (the surface panel’s pinned-last tab)
RealtimeDelegationCardComponentmj-realtime-delegation-card”Working on it” → result card for a delegated agent run
RealtimeChannelStripComponentmj-realtime-channel-stripChip-per-channel strip
RealtimeComposerComponentmj-realtime-composerThe bottom dock: phone-call strip (levels 0–1: mute / captions / Details peek / End) ⇄ fused minis + typed composer (level 2+)
RealtimeSurfaceTabsComponentmj-realtime-surface-tabsTabbed surface panel: channel tabs first, glowing unfocused artifact tabs, Activity pinned last (backed by the framework-free, unit-tested RealtimeSurfaceTabsModel)
WhiteboardArtifactViewerComponentmj-whiteboard-artifact-viewerSaved-board artifact viewer (registered as WhiteboardArtifactViewerPlugin); renders via @memberjunction/ng-whiteboard’s snapshot component

The live whiteboard surface itself (mj-realtime-whiteboard-host, board, toolbar, zoom, “What the agent sees” popover) ships in @memberjunction/ng-whiteboard; the RealtimeWhiteboardChannel plugin here creates it dynamically in a channel tab.

ComponentSelectorDescription
ShareModalComponentmj-share-modalResource sharing modal
MembersModalComponentmj-members-modalMembers management
ExportModalComponentmj-export-modalData export modal
SearchPanelComponentmj-search-panelSearch across conversations
NotificationBadgeComponentmj-notification-badgeUnread notification count
ActivityIndicatorComponentmj-activity-indicatorActive processing indicator
ToastComponentmj-toastToast notification display
InputDialogComponentmj-input-dialogGeneric text input dialog
ImageViewerComponentmj-image-viewerImage attachment viewer
DirectiveSelectorDescription
SearchShortcutDirective[mjSearchShortcut]Keyboard shortcut for search

Message components use dynamic component creation (ViewContainerRef.createComponent) instead of Angular template binding to minimize render cycles and improve performance with large message lists.

All data operations use the MemberJunction entity system:

  • Metadata.GetEntityObject() for entity creation
  • RunView for efficient data loading
  • Proper generic typing throughout

RxJS BehaviorSubject instances for all state, with derived observables using combineLatest and shareReplay(1) for efficient caching.

PackageDescription
@memberjunction/coreCore framework
@memberjunction/core-entitiesEntity type definitions
@memberjunction/globalGlobal utilities
@memberjunction/graphql-dataproviderGraphQL data access
@memberjunction/ng-artifactsArtifact viewer components
@memberjunction/ng-code-editorCode editor component
@memberjunction/ng-container-directivesContainer directives
@memberjunction/ng-markdownMarkdown rendering
@memberjunction/ng-shared-genericShared generic components
@memberjunction/ng-testingTesting framework components
@memberjunction/ng-whiteboardThe generic collaborative whiteboard (consumed by the realtime Whiteboard channel + artifact viewer)
@memberjunction/ai-realtime-clientBrowser-side realtime drivers (OpenAI / Gemini / ElevenLabs / AssemblyAI) used by RealtimeSessionService

Uses @progress/kendo-angular-dialog, @progress/kendo-angular-buttons, @progress/kendo-angular-inputs, @progress/kendo-angular-layout, @progress/kendo-angular-indicators, @progress/kendo-angular-dropdowns, @progress/kendo-angular-notification, @progress/kendo-angular-upload, @progress/kendo-angular-dateinputs.

  • @angular/common ^21.x
  • @angular/core ^21.x
  • @angular/forms ^21.x
  • @angular/router ^21.x
Terminal window
cd packages/Angular/Generic/conversations
npm run build

ISC