@memberjunction/conversations-runtime 0.0.1 → 5.42.0

package/dist/adapters/IActiveTaskTracker.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @fileoverview Active-task tracker adapter — boundary between the runtime's
+ * streaming layer and the host's task-tracking UI.
+ *
+ * `ConversationStreaming` needs to remove a tracked task when its agent run
+ * completes (so the "agent is working…" spinner in the conversation list
+ * clears). The host's task store — Angular's `ActiveTasksService`, a Redux
+ * slice in a React app, anything else — implements this minimal contract.
+ *
+ * The default {@link NoOpActiveTaskTracker} does nothing, which is fine for
+ * server-side / headless callers that don't render a task list.
+ *
+ * @module @memberjunction/conversations-runtime
+ */
+/**
+ * Minimal contract the streaming layer needs from a task tracker.
+ *
+ * Kept deliberately narrow — only `RemoveByAgentRunId` is consumed by
+ * `ConversationStreaming` today. The host's broader task UI (Angular's
+ * `ActiveTasksService` has ~16 methods + multiple observables) stays in
+ * the widget; only the methods the runtime calls are exposed here.
+ *
+ * @example
+ * ```typescript
+ * // Angular host bootstrap
+ * runtime.UseActiveTaskTracker({
+ *     RemoveByAgentRunId: (id) => inject(ActiveTasksService).removeByAgentRunId(id),
+ * });
+ * ```
+ */
+export interface IActiveTaskTracker {
+    /**
+     * Remove a tracked task when its agent run completes.
+     *
+     * @param agentRunId The `MJ: AI Agent Runs` ID whose task should be cleared.
+     * @returns `true` if a task was found and removed, `false` if nothing matched.
+     */
+    RemoveByAgentRunId(agentRunId: string): boolean;
+}
+/**
+ * Default {@link IActiveTaskTracker} that does nothing. Used when no tracker has
+ * been registered — fine for headless / server-side consumers that don't render
+ * task UI. Returns `false` from `RemoveByAgentRunId` to signal "nothing was
+ * tracked," which is the truthful answer in a no-op world.
+ */
+export declare class NoOpActiveTaskTracker implements IActiveTaskTracker {
+    RemoveByAgentRunId(_agentRunId: string): boolean;
+}
+//# sourceMappingURL=IActiveTaskTracker.d.ts.map

package/dist/adapters/IActiveTaskTracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IActiveTaskTracker.d.ts","sourceRoot":"","sources":["../../src/adapters/IActiveTaskTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,kBAAkB;IAC/B;;;;;OAKG;IACH,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CACnD;AAED;;;;;GAKG;AACH,qBAAa,qBAAsB,YAAW,kBAAkB;IACrD,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO;CAG1D"}

package/dist/adapters/IActiveTaskTracker.js

@@ -0,0 +1,26 @@
+/**
+ * @fileoverview Active-task tracker adapter — boundary between the runtime's
+ * streaming layer and the host's task-tracking UI.
+ *
+ * `ConversationStreaming` needs to remove a tracked task when its agent run
+ * completes (so the "agent is working…" spinner in the conversation list
+ * clears). The host's task store — Angular's `ActiveTasksService`, a Redux
+ * slice in a React app, anything else — implements this minimal contract.
+ *
+ * The default {@link NoOpActiveTaskTracker} does nothing, which is fine for
+ * server-side / headless callers that don't render a task list.
+ *
+ * @module @memberjunction/conversations-runtime
+ */
+/**
+ * Default {@link IActiveTaskTracker} that does nothing. Used when no tracker has
+ * been registered — fine for headless / server-side consumers that don't render
+ * task UI. Returns `false` from `RemoveByAgentRunId` to signal "nothing was
+ * tracked," which is the truthful answer in a no-op world.
+ */
+export class NoOpActiveTaskTracker {
+    RemoveByAgentRunId(_agentRunId) {
+        return false;
+    }
+}
+//# sourceMappingURL=IActiveTaskTracker.js.map

package/dist/adapters/IActiveTaskTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IActiveTaskTracker.js","sourceRoot":"","sources":["../../src/adapters/IActiveTaskTracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA4BH;;;;;GAKG;AACH,MAAM,OAAO,qBAAqB;IACvB,kBAAkB,CAAC,WAAmB;QACzC,OAAO,KAAK,CAAC;IACjB,CAAC;CACJ"}

package/dist/adapters/INotificationAdapter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * @fileoverview Notification adapter — boundary between the runtime and the host's
+ * notification UI.
+ *
+ * The runtime needs to surface user-facing messages ("Sage agent not found",
+ * "Agent execution failed", etc.) but must NOT depend on any specific UI library.
+ * Consumers supply an adapter that bridges to whatever notification system the host
+ * uses — Angular's `MJNotificationService`, a React toaster, a Node logger, etc.
+ *
+ * Default (when no adapter is registered): {@link ConsoleNotificationAdapter} logs
+ * to the console. That keeps the runtime usable out of the box without requiring
+ * every consumer to wire something up.
+ *
+ * @module @memberjunction/conversations-runtime
+ */
+/** Severity level for a notification — maps cleanly to most toaster systems. */
+export type NotificationLevel = 'info' | 'success' | 'warning' | 'error';
+/**
+ * Boundary the runtime calls to surface a user-facing message.
+ *
+ * Apps supply an implementation that bridges to their UI toaster (Angular's
+ * `MJNotificationService.CreateSimpleNotification`, a custom React/Vue system,
+ * server-side log sink, etc.) via {@link ConversationsRuntime.UseNotificationAdapter}.
+ *
+ * @example
+ * ```typescript
+ * // Angular host bootstrap
+ * runtime.UseNotificationAdapter({
+ *     Notify: (level, message, ttlMs) => {
+ *         const style = level === 'warning' ? 'warn' : level;  // map names
+ *         MJNotificationService.Instance.CreateSimpleNotification(message, style, ttlMs ?? 5000);
+ *     },
+ * });
+ * ```
+ */
+export interface INotificationAdapter {
+    /**
+     * Surface a notification to the user.
+     *
+     * @param level Severity of the notification.
+     * @param message Human-readable text to display.
+     * @param ttlMs Optional duration in milliseconds. When omitted, the host decides
+     *     (typically 5 seconds for non-error, longer for errors).
+     */
+    Notify(level: NotificationLevel, message: string, ttlMs?: number): void;
+}
+/**
+ * Default {@link INotificationAdapter} that logs to the console. Used when no adapter
+ * has been registered, so the runtime never silently swallows messages.
+ *
+ * - `info` and `success` → `console.log`
+ * - `warning` → `console.warn`
+ * - `error` → `console.error`
+ *
+ * Replace with a UI-backed adapter at host bootstrap for production use.
+ */
+export declare class ConsoleNotificationAdapter implements INotificationAdapter {
+    Notify(level: NotificationLevel, message: string, ttlMs?: number): void;
+}
+//# sourceMappingURL=INotificationAdapter.d.ts.map

package/dist/adapters/INotificationAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"INotificationAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/INotificationAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,gFAAgF;AAChF,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,CAAC;AAEzE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,oBAAoB;IACjC;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3E;AAED;;;;;;;;;GASG;AACH,qBAAa,0BAA2B,YAAW,oBAAoB;IAC5D,MAAM,CAAC,KAAK,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;CAiBjF"}

package/dist/adapters/INotificationAdapter.js

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview Notification adapter — boundary between the runtime and the host's
+ * notification UI.
+ *
+ * The runtime needs to surface user-facing messages ("Sage agent not found",
+ * "Agent execution failed", etc.) but must NOT depend on any specific UI library.
+ * Consumers supply an adapter that bridges to whatever notification system the host
+ * uses — Angular's `MJNotificationService`, a React toaster, a Node logger, etc.
+ *
+ * Default (when no adapter is registered): {@link ConsoleNotificationAdapter} logs
+ * to the console. That keeps the runtime usable out of the box without requiring
+ * every consumer to wire something up.
+ *
+ * @module @memberjunction/conversations-runtime
+ */
+/**
+ * Default {@link INotificationAdapter} that logs to the console. Used when no adapter
+ * has been registered, so the runtime never silently swallows messages.
+ *
+ * - `info` and `success` → `console.log`
+ * - `warning` → `console.warn`
+ * - `error` → `console.error`
+ *
+ * Replace with a UI-backed adapter at host bootstrap for production use.
+ */
+export class ConsoleNotificationAdapter {
+    Notify(level, message, ttlMs) {
+        const ttlNote = ttlMs ? ` (ttl=${ttlMs}ms)` : '';
+        const prefixed = `[conversations-runtime] ${message}${ttlNote}`;
+        switch (level) {
+            case 'error':
+                console.error(prefixed);
+                return;
+            case 'warning':
+                console.warn(prefixed);
+                return;
+            case 'success':
+            case 'info':
+            default:
+                console.log(prefixed);
+                return;
+        }
+    }
+}
+//# sourceMappingURL=INotificationAdapter.js.map

package/dist/adapters/INotificationAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"INotificationAdapter.js","sourceRoot":"","sources":["../../src/adapters/INotificationAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAmCH;;;;;;;;;GASG;AACH,MAAM,OAAO,0BAA0B;IAC5B,MAAM,CAAC,KAAwB,EAAE,OAAe,EAAE,KAAc;QACnE,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QACjD,MAAM,QAAQ,GAAG,2BAA2B,OAAO,GAAG,OAAO,EAAE,CAAC;QAChE,QAAQ,KAAK,EAAE,CAAC;YACZ,KAAK,OAAO;gBACR,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;gBACxB,OAAO;YACX,KAAK,SAAS;gBACV,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACvB,OAAO;YACX,KAAK,SAAS,CAAC;YACf,KAAK,MAAM,CAAC;YACZ;gBACI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACtB,OAAO;QACf,CAAC;IACL,CAAC;CACJ"}

package/dist/adapters/ISessionsAdapter.d.ts

@@ -0,0 +1,124 @@
+/**
+ * @fileoverview Sessions adapter — boundary between the runtime and the host's
+ * realtime sessions infrastructure (PR #2787 — `MJ: AI Agent Sessions` + Channels).
+ *
+ * The runtime needs to surface session lifecycle events (a Voice / Realtime
+ * co-agent session started, a channel within it opened or closed, the session
+ * ended) without depending on any specific UI library or session implementation.
+ * Hosts implement this adapter to bridge their internal session source
+ * (Angular's `RealtimeSessionService` today; future server-bridged voice host,
+ * video-only host, etc.) into a single push stream the runtime exposes.
+ *
+ * Default (when no adapter is registered): {@link NoOpSessionsAdapter} emits
+ * nothing. Headless consumers still work — the
+ * {@link ../sessions/SessionsObserver.SessionsObserver} sub-component subscribes,
+ * sees no events, and the rest of the runtime is unaffected.
+ *
+ * **Multi-source-capable by design.** An adapter implementation can merge
+ * multiple internal services (voice + future video + future server-bridged
+ * realtime) into one observable. The runtime never sees the underlying services.
+ *
+ * **Scope cut — server-only events.** Server-side session closes (janitor
+ * sweep / shutdown) that happen while the user's tab is gone do NOT flow
+ * through this adapter today. Live-session orchestration only; admin/observability
+ * tooling polls the entity for those.
+ *
+ * @module @memberjunction/conversations-runtime
+ */
+import { Observable } from 'rxjs';
+/**
+ * Per-channel state surfaced for `session-channel` events.
+ *
+ * **Why only two values?** `RealtimeSessionService`'s only channel observable is
+ * `ActiveChannels$` (the full plugin set), which fires once on resolve and again
+ * with `[]` on teardown. There's no `opening` / `closing` transition observable
+ * at the channel-plugin level today. Narrowing here is honest about what's
+ * observable; widening later is non-breaking (consumers handling
+ * `'open' | 'closed'` still type-check against `'opening' | 'open' | 'closing'
+ * | 'closed'`).
+ */
+export type SessionChannelState = 'open' | 'closed';
+/**
+ * Why a session ended.
+ *
+ * **Three values, not four.** The server-side `AIAgentSession.CloseReason`
+ * column has four (`Explicit | Janitor | Shutdown | Error`), but only two are
+ * distinguishable client-side (`explicit` = user called `EndVoiceSession`;
+ * `error` = teardown ran from a catch block). `'unknown'` covers any other
+ * client-observable end path. Janitor/shutdown happen out-of-process and never
+ * reach the runtime — see the module-level scope cut.
+ */
+export type SessionEndReason = 'explicit' | 'error' | 'unknown';
+/**
+ * One lifecycle event surfaced by an {@link ISessionsAdapter}.
+ *
+ * Mirrors `MJ: AI Agent Sessions` lifecycle at a deliberately generic level —
+ * no voice/transcript/model fields — so future channel modalities (video,
+ * screen-share, code editor, etc.) emit the same shape.
+ */
+export type SessionLifecycleEvent = {
+    kind: 'session-started';
+    sessionId: string;
+    channelKinds: string[];
+} | {
+    kind: 'session-channel';
+    sessionId: string;
+    channelKind: string;
+    state: SessionChannelState;
+} | {
+    kind: 'session-ended';
+    sessionId: string;
+    reason: SessionEndReason;
+};
+/**
+ * Boundary the runtime subscribes to for session lifecycle.
+ *
+ * Hosts supply an implementation that pushes events from their realtime
+ * session source — the Angular host's `RealtimeSessionsAdapter` bridges
+ * `RealtimeSessionService`'s `SessionStarted$` / `ActiveChannels$` / `SessionEnded$`
+ * observables; a Node CLI or React app would write a different implementation.
+ *
+ * **Single-observable contract.** One `SessionLifecycle$` stream carries all
+ * three event kinds (a discriminated union). Subscribers narrow with the `kind`
+ * tag.
+ *
+ * @example Angular host bootstrap
+ * ```typescript
+ * runtime.UseSessionsAdapter(new RealtimeSessionsAdapter(voiceSessionService));
+ * ```
+ *
+ * @example Multi-source adapter (future)
+ * ```typescript
+ * // When a future video session service ships, merge it with voice — the
+ * // runtime contract doesn't change.
+ * class MultiModalSessionsAdapter implements ISessionsAdapter {
+ *     public readonly SessionLifecycle$ = merge(
+ *         this.voice.SessionLifecycle$,
+ *         this.video.SessionLifecycle$,
+ *     );
+ *     constructor(private voice: RealtimeSessionsAdapter, private video: VideoSessionsAdapter) {}
+ * }
+ * ```
+ */
+export interface ISessionsAdapter {
+    /**
+     * Push stream of session lifecycle events. Subscribers are typically the
+     * runtime's `SessionsObserver`, which re-broadcasts to widget consumers
+     * via `ConversationsRuntime.Instance.Sessions.SessionLifecycle$`.
+     */
+    readonly SessionLifecycle$: Observable<SessionLifecycleEvent>;
+}
+/**
+ * Default {@link ISessionsAdapter} for headless / non-Angular consumers. Emits
+ * nothing — the runtime's `SessionsObserver` still constructs and exposes its
+ * observable; subscribers just never receive events until a real adapter is
+ * registered.
+ *
+ * Existence of this default is a deliberate maintainability call: the runtime
+ * is usable out-of-the-box without forcing every consumer to wire up sessions
+ * infrastructure they may not have.
+ */
+export declare class NoOpSessionsAdapter implements ISessionsAdapter {
+    readonly SessionLifecycle$: Observable<SessionLifecycleEvent>;
+}
+//# sourceMappingURL=ISessionsAdapter.d.ts.map

package/dist/adapters/ISessionsAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISessionsAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/ISessionsAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAS,UAAU,EAAE,MAAM,MAAM,CAAC;AAEzC;;;;;;;;;;GAUG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpD;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAC3B;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,EAAE,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GAC/F;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,UAAU,CAAC,qBAAqB,CAAC,CAAC;CACjE;AAED;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,YAAW,gBAAgB;IACxD,SAAgB,iBAAiB,EAAE,UAAU,CAAC,qBAAqB,CAAC,CAAS;CAChF"}

package/dist/adapters/ISessionsAdapter.js

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Sessions adapter — boundary between the runtime and the host's
+ * realtime sessions infrastructure (PR #2787 — `MJ: AI Agent Sessions` + Channels).
+ *
+ * The runtime needs to surface session lifecycle events (a Voice / Realtime
+ * co-agent session started, a channel within it opened or closed, the session
+ * ended) without depending on any specific UI library or session implementation.
+ * Hosts implement this adapter to bridge their internal session source
+ * (Angular's `RealtimeSessionService` today; future server-bridged voice host,
+ * video-only host, etc.) into a single push stream the runtime exposes.
+ *
+ * Default (when no adapter is registered): {@link NoOpSessionsAdapter} emits
+ * nothing. Headless consumers still work — the
+ * {@link ../sessions/SessionsObserver.SessionsObserver} sub-component subscribes,
+ * sees no events, and the rest of the runtime is unaffected.
+ *
+ * **Multi-source-capable by design.** An adapter implementation can merge
+ * multiple internal services (voice + future video + future server-bridged
+ * realtime) into one observable. The runtime never sees the underlying services.
+ *
+ * **Scope cut — server-only events.** Server-side session closes (janitor
+ * sweep / shutdown) that happen while the user's tab is gone do NOT flow
+ * through this adapter today. Live-session orchestration only; admin/observability
+ * tooling polls the entity for those.
+ *
+ * @module @memberjunction/conversations-runtime
+ */
+import { EMPTY } from 'rxjs';
+/**
+ * Default {@link ISessionsAdapter} for headless / non-Angular consumers. Emits
+ * nothing — the runtime's `SessionsObserver` still constructs and exposes its
+ * observable; subscribers just never receive events until a real adapter is
+ * registered.
+ *
+ * Existence of this default is a deliberate maintainability call: the runtime
+ * is usable out-of-the-box without forcing every consumer to wire up sessions
+ * infrastructure they may not have.
+ */
+export class NoOpSessionsAdapter {
+    constructor() {
+        this.SessionLifecycle$ = EMPTY;
+    }
+}
+//# sourceMappingURL=ISessionsAdapter.js.map

package/dist/adapters/ISessionsAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ISessionsAdapter.js","sourceRoot":"","sources":["../../src/adapters/ISessionsAdapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,KAAK,EAAc,MAAM,MAAM,CAAC;AA8EzC;;;;;;;;;GASG;AACH,MAAM,OAAO,mBAAmB;IAAhC;QACoB,sBAAiB,GAAsC,KAAK,CAAC;IACjF,CAAC;CAAA"}

package/dist/agent-runner/ConversationAgentRunner.d.ts

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Pure-TypeScript agent-run pipeline for conversations.
+ *
+ * Ported from `@memberjunction/ng-conversations/src/lib/services/conversation-agent.service.ts`,
+ * scoped to the core `processMessage` flow. The Angular service's other helpers
+ * (intent checking, sub-agent invocation, artifact lookup, configuration-preset
+ * lookup) stay in the widget for now and can move in a follow-up — they aren't
+ * needed to invoke an agent end-to-end.
+ *
+ * Replaces three Angular bindings from the original:
+ * - `MJNotificationService.Instance.CreateSimpleNotification(...)` →
+ *   {@link IConversationsRuntimeContext.Notification}.
+ * - `AgentClientService` (Angular wrapper over `AgentClientSession`) →
+ *   `AgentClientSession` used directly (already pure-TS).
+ * - Hardcoded `Agents.find(a => a.Name === 'Sage')` → {@link DefaultAgentResolver}.
+ *
+ * @module @memberjunction/conversations-runtime
+ */
+import { Observable } from 'rxjs';
+import { IMetadataProvider } from '@memberjunction/core';
+import { ClientToolRegistry } from '@memberjunction/ai-agent-client';
+import { AgentExecutionProgressCallback, ExecuteAgentResult } from '@memberjunction/ai-core-plus';
+import { MJConversationDetailEntity } from '@memberjunction/core-entities';
+import { IConversationsRuntimeContext } from '../context/IConversationsRuntimeContext.js';
+import { DefaultAgentResolver } from '../default-agent/DefaultAgentResolver.js';
+/**
+ * Inputs to {@link ConversationAgentRunner.processMessage}. Replaces the original
+ * service's positional parameter list with a typed struct so call sites don't
+ * silently break when fields are added or reordered.
+ */
+export interface ProcessMessageInput {
+    /** The conversation this message belongs to. */
+    conversationId: string;
+    /** The just-sent user message (used for `latestMessageId` plumbing). */
+    message: MJConversationDetailEntity;
+    /**
+     * The `MJ: Conversation Details` row that tracks this agent run on the
+     * server. Required for the optimized `RunAIAgentFromConversationDetail` path,
+     * which loads conversation history server-side.
+     */
+    conversationDetailId: string;
+    /**
+     * Application context to inject into the agent's system prompt. Used by
+     * embedders (Form Builder cockpit, Component Studio AI Assistant, future LXP)
+     * to ground the agent in their UI state.
+     */
+    appContext?: Record<string, unknown> | null;
+    /**
+     * Optional progress callback. Mirrors the original service's signature —
+     * embedders forward this through to the widget's progress UI.
+     */
+    onProgress?: AgentExecutionProgressCallback;
+    /**
+     * Optional explicit agent ID. When set, wins over the {@link DefaultAgentResolver}
+     * chain. Mirrors the widget's `[DefaultAgentId]` input.
+     */
+    explicitAgentId?: string | null;
+    /**
+     * Application context for default-agent resolution. App-scoped Application
+     * Settings beat the global default.
+     */
+    applicationId?: string | null;
+}
+/**
+ * Core agent-run orchestrator. Wraps {@link AgentClientSession.RunAgentFromConversationDetail}
+ * with conversation-aware glue: default-agent resolution, permission-filtered
+ * candidate list for Sage's routing decisions, processing-state observable, and
+ * adapter-routed user notifications.
+ *
+ * Usually accessed via `ConversationsRuntime.Instance.AgentRunner`.
+ */
+export declare class ConversationAgentRunner {
+    private readonly context;
+    private readonly resolver;
+    private readonly session;
+    private readonly _isProcessing$;
+    private _provider;
+    /** Emits `true` while an agent run is in flight, `false` otherwise. */
+    readonly isProcessing$: Observable<boolean>;
+    /**
+     * @param context Runtime context — used for notifications. Read on each call
+     *     so adapter swaps after construction are picked up immediately.
+     * @param toolRegistry Shared `ClientToolRegistry` — the runner's internal
+     *     `AgentClientSession` uses this so tools registered on
+     *     `ConversationsRuntime.Tools` are visible to the agent.
+     * @param resolver The runtime's `DefaultAgentResolver` — used to pick the
+     *     conversation manager agent when no explicit ID is supplied.
+     */
+    constructor(context: IConversationsRuntimeContext, toolRegistry: ClientToolRegistry, resolver: DefaultAgentResolver);
+    /**
+     * Metadata provider — falls back to `Metadata.Provider` when unset. Setting
+     * this forwards the provider to the internal `AgentClientSession` so GraphQL
+     * calls target the right server in multi-provider scenarios.
+     */
+    get Provider(): IMetadataProvider;
+    set Provider(value: IMetadataProvider | null);
+    /**
+     * Process a user message through the default conversation manager agent. Mirrors
+     * the original service's `processMessage(...)` flow, but with the three Angular
+     * deps replaced (notification adapter, default-agent resolver, direct
+     * `AgentClientSession`).
+     *
+     * @returns The agent's `ExecuteAgentResult`, or `null` if the agent failed and
+     *     a notification was surfaced.
+     */
+    processMessage(input: ProcessMessageInput): Promise<ExecuteAgentResult | null>;
+    /**
+     * Resolve the agent that should handle this turn — explicit ID wins, then the
+     * Application Settings chain, then the Sage code-const fallback. Surfaces a
+     * notification on failure rather than throwing, so the caller (UI thread)
+     * sees a friendly message.
+     */
+    private resolveAgent;
+    /**
+     * Filter agents by the user's `run` permission. Identical to the original
+     * service's helper — fails closed on per-agent error so we never expose an
+     * agent the user shouldn't see.
+     */
+    private filterAgentsByPermissions;
+}
+//# sourceMappingURL=ConversationAgentRunner.d.ts.map

package/dist/agent-runner/ConversationAgentRunner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationAgentRunner.d.ts","sourceRoot":"","sources":["../../src/agent-runner/ConversationAgentRunner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAmB,UAAU,EAAE,MAAM,MAAM,CAAC;AACnD,OAAO,EAAE,iBAAiB,EAAsB,MAAM,sBAAsB,CAAC;AAE7E,OAAO,EAEH,kBAAkB,EAErB,MAAM,iCAAiC,CAAC;AAKzC,OAAO,EACH,8BAA8B,EAC9B,kBAAkB,EAErB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAAE,0BAA0B,EAAE,MAAM,+BAA+B,CAAC;AAE3E,OAAO,EAAE,4BAA4B,EAAE,MAAM,yCAAyC,CAAC;AACvF,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;AAE7E;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAChC,gDAAgD;IAChD,cAAc,EAAE,MAAM,CAAC;IACvB,wEAAwE;IACxE,OAAO,EAAE,0BAA0B,CAAC;IACpC;;;;OAIG;IACH,oBAAoB,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC5C;;;OAGG;IACH,UAAU,CAAC,EAAE,8BAA8B,CAAC;IAC5C;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,qBAAa,uBAAuB;IAkB5B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAExB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAnB7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuC;IACtE,OAAO,CAAC,SAAS,CAAkC;IAEnD,uEAAuE;IACvE,SAAgB,aAAa,EAAE,UAAU,CAAC,OAAO,CAAC,CAAsC;IAExF;;;;;;;;OAQG;gBAEkB,OAAO,EAAE,4BAA4B,EACtD,YAAY,EAAE,kBAAkB,EACf,QAAQ,EAAE,oBAAoB;IAKnD;;;;OAIG;IACH,IAAW,QAAQ,IAAI,iBAAiB,CAEvC;IACD,IAAW,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,EAGlD;IAED;;;;;;;;OAQG;IACU,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC;IAgG3F;;;;;OAKG;YACW,YAAY;IAkB1B;;;;OAIG;YACW,yBAAyB;CAyB1C"}