@memberjunction/conversations-runtime 0.0.1 → 5.41.0

package/README.md

@@ -1,45 +1,101 @@
 # @memberjunction/conversations-runtime
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/conversations-runtime`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+Framework-agnostic runtime layer for MemberJunction conversational AI experiences.
+
+## What this package is
+
+The pure-TypeScript orchestration layer that sits beneath every chat surface in MJ — overlay, embedded panel, full-page Chat workspace, and any future custom UX. **Zero UX dependencies**, **client + server consumable**.
+
+```
+┌──────────────────────────────────────┐   ┌──────────────────────────────────────┐
+│  ANGULAR APPS                         │   │  NON-ANGULAR JS APPS                  │
+│  (MJ Explorer, Angular widgets)       │   │  (React, Vue, Node workers, CLI)     │
+└──────────────────────────────────────┘   └──────────────────────────────────────┘
+                  │                                            │
+                  ▼                                            │
+        @memberjunction/ng-conversations                       │
+        (Angular widget wrapper)                                │
+                  │                                            │
+                  └──────────────────┬─────────────────────────┘
+                                     ▼
+                    @memberjunction/conversations-runtime   ★ this package
+                                     │
+                                     ▼
+            @memberjunction/core-entities (ConversationEngine — data layer)
+```
+
+## What it provides
+
+| Sub-component | Purpose |
+|---|---|
+| `Mentions` | Parse `@`-mentions out of message text (JSON + legacy formats). Pure string logic. |
+| `Bridge` | Coordinate active-conversation state between the corner overlay and the full-page workspace. |
+| `DefaultAgent` | Resolve which agent handles a conversation turn via Application-Settings-driven chain (explicit → app-scoped → global → code-const Sage fallback). |
+| `Tools` | The shared `ClientToolRegistry` from `@memberjunction/ai-agent-client` — register tools the agent can invoke on the client. |
+| `AgentRunner` | Orchestrates `processMessage` — resolves the target agent, filters candidates, dispatches via `AgentClientSession`. |
+| `Streaming` | Routes per-message progress + completion events from the server's PubSub channel to consumer callbacks. |
+| `Sessions` | Observability over the AI Agent Sessions/Channels infrastructure from PR #2787. Hosts register an `ISessionsAdapter` at bootstrap; the runtime re-broadcasts session lifecycle events as `'session-started' \| 'session-channel' \| 'session-ended'`. |
+
+## Adapter slots (the host-runtime boundary)
+
+The runtime needs UI affordances (toasts, active-task indicators, session lifecycle observability) but cannot import any framework. Hosts implement small interfaces and register them at bootstrap:
+
+| Interface | What the runtime calls | Default (no host wiring) |
+|---|---|---|
+| `INotificationAdapter` | `Notify(level, message, ttlMs?)` | `ConsoleNotificationAdapter` (console.log/warn/error) |
+| `IActiveTaskTracker` | `RemoveByAgentRunId(agentRunId)` | `NoOpActiveTaskTracker` |
+| `ISessionsAdapter` | (observable) `SessionLifecycle$` | `NoOpSessionsAdapter` (EMPTY observable) |
+
+Registration:
+```typescript
+ConversationsRuntime.Instance.UseNotificationAdapter({ Notify: (...) => {} });
+ConversationsRuntime.Instance.UseActiveTaskTracker({ RemoveByAgentRunId: (...) => {} });
+ConversationsRuntime.Instance.UseSessionsAdapter(myAdapter);
+```
+
+In `@memberjunction/ng-conversations`, `ConversationsRuntimeBootstrap` registers all three automatically on first DI injection.
+
+## Pre-warming
+
+`ConversationsRuntime` is decorated with `@RegisterForStartup({ deferred: true, deferredDelay: 5000, severity: 'warn' })`. 5 seconds after app boot, the MJ startup manager fires `HandleStartup()`, which calls `Config(false)` — pre-loading dependent engines in the background. Non-blocking; failures log as warnings.
+
+## Quick start
+
+```typescript
+import { ConversationsRuntime } from '@memberjunction/conversations-runtime';
+
+// At app boot — lazy, idempotent, no penalty if called per entry point
+await ConversationsRuntime.Instance.Config(false, contextUser);
+
+// Parse a mention out of user text
+const mentions = ConversationsRuntime.Instance.Mentions.parseMentions(
+    '@Sage help me',
+    AIEngineBase.Instance.Agents
+);
+
+// Resolve the default agent for the current application
+const agent = await ConversationsRuntime.Instance.DefaultAgent.resolve({
+    applicationId: currentAppId,
+});
+
+// Register a client tool the agent can invoke
+ConversationsRuntime.Instance.Tools.Register({
+    Name: 'NavigateToRecord',
+    Description: 'Open an entity record in the UI',
+    ParameterSchema: { type: 'object', properties: { EntityName: { type: 'string' } } },
+    Handler: async (params) => {
+        // ... your navigation code ...
+        return { Success: true };
+    },
+});
+```
+
+## Multi-provider support
+
+Every API accepts an optional `provider?: IMetadataProvider` parameter and falls back to `Metadata.Provider` when omitted. Apps connecting to multiple MJ servers in parallel should pass an explicit provider to scope the runtime to that server.
+
+## Documentation
+
+- See [`guides/CONVERSATIONS_UX_STACK_GUIDE.md`](../../guides/CONVERSATIONS_UX_STACK_GUIDE.md) for the full three-layer stack reference — slots, events, tokens, default-agent resolution, sessions adapter, multi-provider considerations, recipes.
+- See [`guides/REALTIME_CO_AGENTS_GUIDE.md`](../../guides/REALTIME_CO_AGENTS_GUIDE.md) (PR #2787) for the Sessions/Channels/realtime infrastructure this runtime bridges to.
+- See [`plans/conversations-runtime-extraction.md`](../../plans/conversations-runtime-extraction.md) for the design rationale.

package/dist/ConversationsRuntime.d.ts

@@ -0,0 +1,193 @@
+/**
+ * @fileoverview Top-level runtime singleton for the conversations stack.
+ *
+ * `ConversationsRuntime` is the single composition root for the orchestration concerns of
+ * MJ's conversational AI experiences. It holds and exposes the sub-components (mentions,
+ * bridge, default-agent resolver, client-tool registry, sessions observer, streaming,
+ * agent runner) and provides a lazy `Config()` for boot-time loading of the engines
+ * it depends on.
+ *
+ * It follows MJ's established `BaseEngine` / `BaseSingleton` idiom — singleton via the
+ * global object store, idempotent lazy `Config()`, and an explicit `Instance` accessor.
+ *
+ * **Two engines, two concerns.** This runtime is NOT a wrapper around `ConversationEngine`
+ * (data layer in `@memberjunction/core-entities`). Data CRUD goes through
+ * `ConversationEngine.Instance`; orchestration goes through `ConversationsRuntime.Instance`.
+ * The runtime delegates to the data engine where needed but does not re-export its API.
+ *
+ * **Adapter pattern.** The runtime is framework-agnostic but needs to surface
+ * notifications and clear running tasks in the host's UI. Hosts inject adapters via
+ * {@link UseNotificationAdapter} / {@link UseActiveTaskTracker} at bootstrap. Defaults
+ * (`ConsoleNotificationAdapter`, `NoOpActiveTaskTracker`) keep the runtime usable
+ * out of the box for server-side / headless callers.
+ *
+ * @module @memberjunction/conversations-runtime
+ */
+import { BaseEngine, IMetadataProvider, IStartupSink, UserInfo } from '@memberjunction/core';
+import { ClientToolRegistry } from '@memberjunction/ai-agent-client';
+import { MentionParser } from './mentions/MentionParser.js';
+import { ConversationBridge } from './bridge/ConversationBridge.js';
+import { DefaultAgentResolver } from './default-agent/DefaultAgentResolver.js';
+import { SessionsObserver } from './sessions/SessionsObserver.js';
+import { ConversationStreaming } from './streaming/ConversationStreaming.js';
+import { ConversationAgentRunner } from './agent-runner/ConversationAgentRunner.js';
+import { INotificationAdapter } from './adapters/INotificationAdapter.js';
+import { IActiveTaskTracker } from './adapters/IActiveTaskTracker.js';
+import { ISessionsAdapter } from './adapters/ISessionsAdapter.js';
+import { IConversationsRuntimeContext } from './context/IConversationsRuntimeContext.js';
+/**
+ * The framework-agnostic conversations runtime.
+ *
+ * **Lifecycle:** call `Config(false, contextUser, provider)` at every entry point that
+ * uses the runtime — it's idempotent, so only the first caller pays the load cost. The
+ * rest are O(1) cache hits.
+ *
+ * **Adapters:** at host bootstrap, supply UI adapters via
+ * {@link UseNotificationAdapter} / {@link UseActiveTaskTracker}. Until you do, the
+ * defaults log to the console and no-op respectively.
+ *
+ * **Multi-provider:** when an explicit provider is passed to `Config()`, the runtime
+ * scopes its dependent engines (`AIEngineBase`, `ApplicationSettingEngine`,
+ * `ConversationEngine`) to that provider. Single-provider apps omit the parameter and
+ * get the global default.
+ *
+ * @example
+ * ```typescript
+ * import { ConversationsRuntime } from '@memberjunction/conversations-runtime';
+ *
+ * // At every entry point (no-op after the first call)
+ * await ConversationsRuntime.Instance.Config(false, contextUser);
+ *
+ * // Wire UI adapters once at bootstrap
+ * ConversationsRuntime.Instance.UseNotificationAdapter({
+ *     Notify: (level, msg, ttl) =>
+ *         MJNotificationService.Instance.CreateSimpleNotification(msg, level, ttl ?? 5000),
+ * });
+ *
+ * // Process a message through the default conversation manager agent
+ * const result = await ConversationsRuntime.Instance.AgentRunner.processMessage({
+ *     conversationId,
+ *     message,
+ *     conversationDetailId,
+ *     applicationId,
+ * });
+ * ```
+ */
+export declare class ConversationsRuntime extends BaseEngine<ConversationsRuntime> implements IConversationsRuntimeContext, IStartupSink {
+    /**
+     * The singleton instance. Backed by the Global Object Store so the same instance is
+     * shared even when bundlers duplicate this module across code splits.
+     */
+    static get Instance(): ConversationsRuntime;
+    private _notification;
+    private _tasks;
+    /**
+     * Currently registered notification adapter — used by sub-components to surface
+     * user-visible messages. Defaults to {@link ConsoleNotificationAdapter}.
+     *
+     * Implements {@link IConversationsRuntimeContext.Notification}.
+     */
+    get Notification(): INotificationAdapter;
+    /**
+     * Currently registered active-task tracker — used by `ConversationStreaming` to
+     * clear running tasks when an agent run completes. Defaults to
+     * {@link NoOpActiveTaskTracker}.
+     *
+     * Implements {@link IConversationsRuntimeContext.Tasks}.
+     */
+    get Tasks(): IActiveTaskTracker;
+    /**
+     * Register a notification adapter — typically called once at host bootstrap.
+     * The new adapter takes effect immediately; sub-components read it from the
+     * context on every call.
+     */
+    UseNotificationAdapter(adapter: INotificationAdapter): void;
+    /**
+     * Register an active-task tracker — typically called once at host bootstrap.
+     * The new tracker takes effect immediately.
+     */
+    UseActiveTaskTracker(tracker: IActiveTaskTracker): void;
+    /**
+     * Register a sessions adapter — bridges the host's realtime session source
+     * (e.g., Angular's `RealtimeSessionService`) to the framework-agnostic runtime
+     * `Sessions` observer. Typically called once at host bootstrap; multiple
+     * swaps are supported (test harnesses, modality additions).
+     *
+     * Delegates to {@link SessionsObserver.UseSessionsAdapter}, which cleanly
+     * tears down any prior adapter subscription before subscribing to the new
+     * one. The new adapter takes effect immediately for all subscribers of
+     * `Sessions.SessionLifecycle$`.
+     */
+    UseSessionsAdapter(adapter: ISessionsAdapter): void;
+    private readonly _mentions;
+    private readonly _bridge;
+    private readonly _tools;
+    private readonly _defaultAgent;
+    private readonly _sessions;
+    private _streaming?;
+    private _agentRunner?;
+    /** Mention parser — pure string logic. See {@link MentionParser}. */
+    get Mentions(): MentionParser;
+    /** Overlay ⇄ workspace coordination bus. See {@link ConversationBridge}. */
+    get Bridge(): ConversationBridge;
+    /**
+     * Shared client-tool registry — the same `ClientToolRegistry` from
+     * `@memberjunction/ai-agent-client` that `AgentClientSession` consumes. Apps register
+     * tools here once at startup; every session sees them.
+     */
+    get Tools(): ClientToolRegistry;
+    /** Default-agent resolution chain. See {@link DefaultAgentResolver}. */
+    get DefaultAgent(): DefaultAgentResolver;
+    /**
+     * Sessions/Channels lifecycle observer — surfaces realtime session lifecycle
+     * events from the registered {@link ISessionsAdapter}. Defaults to a no-op
+     * adapter so headless consumers still construct cleanly; the Angular host's
+     * `ConversationsRuntimeBootstrap` swaps in a `RealtimeSessionsAdapter` that
+     * bridges `RealtimeSessionService` from PR #2787.
+     *
+     * Subscribe to `Sessions.SessionLifecycle$` for `session-started` /
+     * `session-channel` / `session-ended` events. See {@link SessionsObserver}.
+     */
+    get Sessions(): SessionsObserver;
+    /**
+     * PubSub streaming layer — routes progress and completion events from the server
+     * to per-message callbacks. See {@link ConversationStreaming}.
+     *
+     * Hosts must call `.initialize()` once after `Config()` to open the subscription.
+     */
+    get Streaming(): ConversationStreaming;
+    /**
+     * Agent-run orchestrator — wraps `AgentClientSession.RunAgentFromConversationDetail`
+     * with default-agent resolution and permission-filtered candidate lists. See
+     * {@link ConversationAgentRunner}.
+     */
+    get AgentRunner(): ConversationAgentRunner;
+    /**
+     * Lazy-load the engines this runtime depends on (`AIEngineBase`,
+     * `ApplicationSettingEngine`, `ConversationEngine`). Safe to call from every entry
+     * point — only the first invocation pays the load cost.
+     *
+     * The runtime itself currently has no `BaseEnginePropertyConfig` entries — the data
+     * lives in the dependent engines. We override `Config()` rather than delegating to
+     * `super.Load()` because we're a composition root, not a data cache.
+     *
+     * @param forceRefresh Refresh the dependent engines' caches.
+     * @param contextUser Required on the server; ignored when omitted on the browser.
+     * @param provider Bind to a specific metadata provider; falls back to `Metadata.Provider`.
+     */
+    Config(forceRefresh?: boolean, contextUser?: UserInfo, provider?: IMetadataProvider): Promise<void>;
+    /**
+     * {@link IStartupSink} entry point fired by the MJ startup manager when this class
+     * is registered via `@RegisterForStartup`. Pre-warms the runtime so the first user
+     * to open a conversations surface doesn't pay the load cost. Deferred + non-blocking
+     * per the decorator config — failures are logged (`severity: 'warn'`) but never
+     * block app boot.
+     */
+    HandleStartup(contextUser?: UserInfo, provider?: IMetadataProvider): Promise<void>;
+    /**
+     * Tear down sub-components that hold subscriptions. Safe to call at app shutdown or
+     * in tests between cases.
+     */
+    Dispose(): void;
+}
+//# sourceMappingURL=ConversationsRuntime.d.ts.map

package/dist/ConversationsRuntime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationsRuntime.d.ts","sourceRoot":"","sources":["../src/ConversationsRuntime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,YAAY,EAAsB,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAGjH,OAAO,EAAE,kBAAkB,EAAE,MAAM,iCAAiC,CAAC;AAErE,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAC5E,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,qBAAqB,EAAE,MAAM,mCAAmC,CAAC;AAC1E,OAAO,EAAE,uBAAuB,EAAE,MAAM,wCAAwC,CAAC;AACjF,OAAO,EACH,oBAAoB,EAEvB,MAAM,iCAAiC,CAAC;AACzC,OAAO,EACH,kBAAkB,EAErB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACH,gBAAgB,EACnB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EAAE,4BAA4B,EAAE,MAAM,wCAAwC,CAAC;AAEtF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,qBAMa,oBACT,SAAQ,UAAU,CAAC,oBAAoB,CACvC,YAAW,4BAA4B,EAAE,YAAY;IAErD;;;OAGG;IACH,WAAkB,QAAQ,IAAI,oBAAoB,CAEjD;IAMD,OAAO,CAAC,aAAa,CAA0D;IAC/E,OAAO,CAAC,MAAM,CAAmD;IAEjE;;;;;OAKG;IACH,IAAW,YAAY,IAAI,oBAAoB,CAE9C;IAED;;;;;;OAMG;IACH,IAAW,KAAK,IAAI,kBAAkB,CAErC;IAED;;;;OAIG;IACI,sBAAsB,CAAC,OAAO,EAAE,oBAAoB,GAAG,IAAI;IAIlE;;;OAGG;IACI,oBAAoB,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI;IAI9D;;;;;;;;;;OAUG;IACI,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAS1D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA8B;IAC5D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA0B;IAKpD,OAAO,CAAC,UAAU,CAAC,CAAwB;IAC3C,OAAO,CAAC,YAAY,CAAC,CAA0B;IAE/C,qEAAqE;IACrE,IAAW,QAAQ,IAAI,aAAa,CAEnC;IAED,4EAA4E;IAC5E,IAAW,MAAM,IAAI,kBAAkB,CAEtC;IAED;;;;OAIG;IACH,IAAW,KAAK,IAAI,kBAAkB,CAErC;IAED,wEAAwE;IACxE,IAAW,YAAY,IAAI,oBAAoB,CAE9C;IAED;;;;;;;;;OASG;IACH,IAAW,QAAQ,IAAI,gBAAgB,CAEtC;IAED;;;;;OAKG;IACH,IAAW,SAAS,IAAI,qBAAqB,CAK5C;IAED;;;;OAIG;IACH,IAAW,WAAW,IAAI,uBAAuB,CAKhD;IAMD;;;;;;;;;;;;OAYG;IACU,MAAM,CACf,YAAY,CAAC,EAAE,OAAO,EACtB,WAAW,CAAC,EAAE,QAAQ,EACtB,QAAQ,CAAC,EAAE,iBAAiB,GAC7B,OAAO,CAAC,IAAI,CAAC;IAUhB;;;;;;OAMG;IACU,aAAa,CAAC,WAAW,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/F;;;OAGG;IACI,OAAO,IAAI,IAAI;CAQzB"}

package/dist/ConversationsRuntime.js

@@ -0,0 +1,268 @@
+/**
+ * @fileoverview Top-level runtime singleton for the conversations stack.
+ *
+ * `ConversationsRuntime` is the single composition root for the orchestration concerns of
+ * MJ's conversational AI experiences. It holds and exposes the sub-components (mentions,
+ * bridge, default-agent resolver, client-tool registry, sessions observer, streaming,
+ * agent runner) and provides a lazy `Config()` for boot-time loading of the engines
+ * it depends on.
+ *
+ * It follows MJ's established `BaseEngine` / `BaseSingleton` idiom — singleton via the
+ * global object store, idempotent lazy `Config()`, and an explicit `Instance` accessor.
+ *
+ * **Two engines, two concerns.** This runtime is NOT a wrapper around `ConversationEngine`
+ * (data layer in `@memberjunction/core-entities`). Data CRUD goes through
+ * `ConversationEngine.Instance`; orchestration goes through `ConversationsRuntime.Instance`.
+ * The runtime delegates to the data engine where needed but does not re-export its API.
+ *
+ * **Adapter pattern.** The runtime is framework-agnostic but needs to surface
+ * notifications and clear running tasks in the host's UI. Hosts inject adapters via
+ * {@link UseNotificationAdapter} / {@link UseActiveTaskTracker} at bootstrap. Defaults
+ * (`ConsoleNotificationAdapter`, `NoOpActiveTaskTracker`) keep the runtime usable
+ * out of the box for server-side / headless callers.
+ *
+ * @module @memberjunction/conversations-runtime
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseEngine, RegisterForStartup } from '@memberjunction/core';
+import { AIEngineBase } from '@memberjunction/ai-engine-base';
+import { ApplicationSettingEngine, ConversationEngine } from '@memberjunction/core-entities';
+import { ClientToolRegistry } from '@memberjunction/ai-agent-client';
+import { MentionParser } from './mentions/MentionParser.js';
+import { ConversationBridge } from './bridge/ConversationBridge.js';
+import { DefaultAgentResolver } from './default-agent/DefaultAgentResolver.js';
+import { SessionsObserver } from './sessions/SessionsObserver.js';
+import { ConversationStreaming } from './streaming/ConversationStreaming.js';
+import { ConversationAgentRunner } from './agent-runner/ConversationAgentRunner.js';
+import { ConsoleNotificationAdapter, } from './adapters/INotificationAdapter.js';
+import { NoOpActiveTaskTracker, } from './adapters/IActiveTaskTracker.js';
+/**
+ * The framework-agnostic conversations runtime.
+ *
+ * **Lifecycle:** call `Config(false, contextUser, provider)` at every entry point that
+ * uses the runtime — it's idempotent, so only the first caller pays the load cost. The
+ * rest are O(1) cache hits.
+ *
+ * **Adapters:** at host bootstrap, supply UI adapters via
+ * {@link UseNotificationAdapter} / {@link UseActiveTaskTracker}. Until you do, the
+ * defaults log to the console and no-op respectively.
+ *
+ * **Multi-provider:** when an explicit provider is passed to `Config()`, the runtime
+ * scopes its dependent engines (`AIEngineBase`, `ApplicationSettingEngine`,
+ * `ConversationEngine`) to that provider. Single-provider apps omit the parameter and
+ * get the global default.
+ *
+ * @example
+ * ```typescript
+ * import { ConversationsRuntime } from '@memberjunction/conversations-runtime';
+ *
+ * // At every entry point (no-op after the first call)
+ * await ConversationsRuntime.Instance.Config(false, contextUser);
+ *
+ * // Wire UI adapters once at bootstrap
+ * ConversationsRuntime.Instance.UseNotificationAdapter({
+ *     Notify: (level, msg, ttl) =>
+ *         MJNotificationService.Instance.CreateSimpleNotification(msg, level, ttl ?? 5000),
+ * });
+ *
+ * // Process a message through the default conversation manager agent
+ * const result = await ConversationsRuntime.Instance.AgentRunner.processMessage({
+ *     conversationId,
+ *     message,
+ *     conversationDetailId,
+ *     applicationId,
+ * });
+ * ```
+ */
+let ConversationsRuntime = class ConversationsRuntime extends BaseEngine {
+    constructor() {
+        super(...arguments);
+        // ────────────────────────────────────────────────────────────────────
+        // Adapter slots — replaceable at host bootstrap. Defaults below.
+        // ────────────────────────────────────────────────────────────────────
+        this._notification = new ConsoleNotificationAdapter();
+        this._tasks = new NoOpActiveTaskTracker();
+        // ────────────────────────────────────────────────────────────────────
+        // Sub-components — eagerly constructed (cheap) so the Instance accessor
+        // always returns a ready runtime.
+        // ────────────────────────────────────────────────────────────────────
+        this._mentions = new MentionParser();
+        this._bridge = new ConversationBridge();
+        this._tools = new ClientToolRegistry();
+        this._defaultAgent = new DefaultAgentResolver();
+        this._sessions = new SessionsObserver();
+    }
+    /**
+     * The singleton instance. Backed by the Global Object Store so the same instance is
+     * shared even when bundlers duplicate this module across code splits.
+     */
+    static get Instance() {
+        return super.getInstance();
+    }
+    /**
+     * Currently registered notification adapter — used by sub-components to surface
+     * user-visible messages. Defaults to {@link ConsoleNotificationAdapter}.
+     *
+     * Implements {@link IConversationsRuntimeContext.Notification}.
+     */
+    get Notification() {
+        return this._notification;
+    }
+    /**
+     * Currently registered active-task tracker — used by `ConversationStreaming` to
+     * clear running tasks when an agent run completes. Defaults to
+     * {@link NoOpActiveTaskTracker}.
+     *
+     * Implements {@link IConversationsRuntimeContext.Tasks}.
+     */
+    get Tasks() {
+        return this._tasks;
+    }
+    /**
+     * Register a notification adapter — typically called once at host bootstrap.
+     * The new adapter takes effect immediately; sub-components read it from the
+     * context on every call.
+     */
+    UseNotificationAdapter(adapter) {
+        this._notification = adapter;
+    }
+    /**
+     * Register an active-task tracker — typically called once at host bootstrap.
+     * The new tracker takes effect immediately.
+     */
+    UseActiveTaskTracker(tracker) {
+        this._tasks = tracker;
+    }
+    /**
+     * Register a sessions adapter — bridges the host's realtime session source
+     * (e.g., Angular's `RealtimeSessionService`) to the framework-agnostic runtime
+     * `Sessions` observer. Typically called once at host bootstrap; multiple
+     * swaps are supported (test harnesses, modality additions).
+     *
+     * Delegates to {@link SessionsObserver.UseSessionsAdapter}, which cleanly
+     * tears down any prior adapter subscription before subscribing to the new
+     * one. The new adapter takes effect immediately for all subscribers of
+     * `Sessions.SessionLifecycle$`.
+     */
+    UseSessionsAdapter(adapter) {
+        this._sessions.UseSessionsAdapter(adapter);
+    }
+    /** Mention parser — pure string logic. See {@link MentionParser}. */
+    get Mentions() {
+        return this._mentions;
+    }
+    /** Overlay ⇄ workspace coordination bus. See {@link ConversationBridge}. */
+    get Bridge() {
+        return this._bridge;
+    }
+    /**
+     * Shared client-tool registry — the same `ClientToolRegistry` from
+     * `@memberjunction/ai-agent-client` that `AgentClientSession` consumes. Apps register
+     * tools here once at startup; every session sees them.
+     */
+    get Tools() {
+        return this._tools;
+    }
+    /** Default-agent resolution chain. See {@link DefaultAgentResolver}. */
+    get DefaultAgent() {
+        return this._defaultAgent;
+    }
+    /**
+     * Sessions/Channels lifecycle observer — surfaces realtime session lifecycle
+     * events from the registered {@link ISessionsAdapter}. Defaults to a no-op
+     * adapter so headless consumers still construct cleanly; the Angular host's
+     * `ConversationsRuntimeBootstrap` swaps in a `RealtimeSessionsAdapter` that
+     * bridges `RealtimeSessionService` from PR #2787.
+     *
+     * Subscribe to `Sessions.SessionLifecycle$` for `session-started` /
+     * `session-channel` / `session-ended` events. See {@link SessionsObserver}.
+     */
+    get Sessions() {
+        return this._sessions;
+    }
+    /**
+     * PubSub streaming layer — routes progress and completion events from the server
+     * to per-message callbacks. See {@link ConversationStreaming}.
+     *
+     * Hosts must call `.initialize()` once after `Config()` to open the subscription.
+     */
+    get Streaming() {
+        if (!this._streaming) {
+            this._streaming = new ConversationStreaming(this);
+        }
+        return this._streaming;
+    }
+    /**
+     * Agent-run orchestrator — wraps `AgentClientSession.RunAgentFromConversationDetail`
+     * with default-agent resolution and permission-filtered candidate lists. See
+     * {@link ConversationAgentRunner}.
+     */
+    get AgentRunner() {
+        if (!this._agentRunner) {
+            this._agentRunner = new ConversationAgentRunner(this, this._tools, this._defaultAgent);
+        }
+        return this._agentRunner;
+    }
+    // ────────────────────────────────────────────────────────────────────
+    // Lifecycle
+    // ────────────────────────────────────────────────────────────────────
+    /**
+     * Lazy-load the engines this runtime depends on (`AIEngineBase`,
+     * `ApplicationSettingEngine`, `ConversationEngine`). Safe to call from every entry
+     * point — only the first invocation pays the load cost.
+     *
+     * The runtime itself currently has no `BaseEnginePropertyConfig` entries — the data
+     * lives in the dependent engines. We override `Config()` rather than delegating to
+     * `super.Load()` because we're a composition root, not a data cache.
+     *
+     * @param forceRefresh Refresh the dependent engines' caches.
+     * @param contextUser Required on the server; ignored when omitted on the browser.
+     * @param provider Bind to a specific metadata provider; falls back to `Metadata.Provider`.
+     */
+    async Config(forceRefresh, contextUser, provider) {
+        // Run dependent-engine configs in parallel — they're independent, and the first
+        // call to each is what pays the cost. Subsequent calls are no-ops.
+        await Promise.all([
+            AIEngineBase.Instance.Config(forceRefresh, contextUser, provider),
+            ApplicationSettingEngine.Instance.Config(forceRefresh, contextUser, provider),
+            ConversationEngine.Instance.Config(forceRefresh, contextUser, provider),
+        ]);
+    }
+    /**
+     * {@link IStartupSink} entry point fired by the MJ startup manager when this class
+     * is registered via `@RegisterForStartup`. Pre-warms the runtime so the first user
+     * to open a conversations surface doesn't pay the load cost. Deferred + non-blocking
+     * per the decorator config — failures are logged (`severity: 'warn'`) but never
+     * block app boot.
+     */
+    async HandleStartup(contextUser, provider) {
+        await this.Config(false, contextUser, provider);
+    }
+    /**
+     * Tear down sub-components that hold subscriptions. Safe to call at app shutdown or
+     * in tests between cases.
+     */
+    Dispose() {
+        this._sessions.Dispose();
+        if (this._streaming) {
+            this._streaming.Dispose();
+            this._streaming = undefined;
+        }
+        this._agentRunner = undefined;
+    }
+};
+ConversationsRuntime = __decorate([
+    RegisterForStartup({
+        deferred: true,
+        deferredDelay: 5000,
+        severity: 'warn',
+        description: 'Conversations runtime (mentions, default-agent, agent runner) pre-warming'
+    })
+], ConversationsRuntime);
+export { ConversationsRuntime };
+//# sourceMappingURL=ConversationsRuntime.js.map

package/dist/ConversationsRuntime.js.map

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