@memberjunction/ng-conversations 5.40.2 → 5.41.0

package/dist/lib/services/mention-parser.service.js

@@ -1,261 +1,50 @@
-import { Injectable } from '@angular/core';
-import { ConversationUtility } from '@memberjunction/ai-core-plus';
-import * as i0 from "@angular/core";
 /**
- * Service for parsing @mentions from message text
- * Supports both JSON format and legacy text format
+ * @fileoverview Angular DI shim over the framework-agnostic `MentionParser` from
+ * `@memberjunction/conversations-runtime`.
+ *
+ * Previously this service owned the regex-based mention-parsing logic. That logic
+ * moved into the runtime in PR 1; this file is now a thin pass-through so existing
+ * `inject(MentionParserService)` call sites keep working without changes.
+ *
+ * **For new code:** prefer `ConversationsRuntime.Instance.Mentions` directly.
  */
+import { Injectable } from '@angular/core';
+import { ConversationsRuntime } from '@memberjunction/conversations-runtime';
+import * as i0 from "@angular/core";
+import * as i1 from "./conversations-runtime-bootstrap.service";
+// NOTE: `Mention` and `MentionParseResult` are NOT re-exported from this file —
+// the model's `conversation-state.model.ts` already exports `MentionParseResult`,
+// and re-exporting here causes a public-api ambiguity. Consumers wanting the
+// runtime's types should import from `@memberjunction/conversations-runtime`.
 export class MentionParserService {
-    // Regex to match JSON mentions: @{type:"agent",id:"uuid",name:"Name",configId:"uuid",config:"High"}
-    JSON_MENTION_REGEX = /@\{[^}]+\}/g;
-    // Regex to match legacy @mentions - supports names with spaces if quoted: @"Agent Name" or @AgentName
-    LEGACY_MENTION_REGEX = /@"([^"]+)"|@(\S+)/g;
-    constructor() { }
-    /**
-     * Parse mentions from message text
-     * Supports both JSON format (@{type:"agent",id:"uuid",...}) and legacy text format (@AgentName)
-     * @param text The message text to parse
-     * @param availableAgents List of available agents for matching
-     * @param availableUsers List of available users for matching (optional)
-     * @returns Parsed mentions with agent and user separation
-     */
-    parseMentions(text, availableAgents, availableUsers) {
-        const mentions = [];
-        // First, try to parse JSON mentions (new format)
-        const jsonMatches = Array.from(text.matchAll(this.JSON_MENTION_REGEX));
-        for (const match of jsonMatches) {
-            try {
-                // Extract JSON string (remove @ prefix)
-                const jsonStr = match[0].substring(1); // Remove '@'
-                const mentionData = JSON.parse(jsonStr);
-                // Validate required fields
-                if (mentionData.type && mentionData.id && mentionData.name) {
-                    const mention = {
-                        type: mentionData.type,
-                        id: mentionData.id,
-                        name: mentionData.name
-                    };
-                    // Add configuration if present (for agents)
-                    if (mentionData.configId) {
-                        mention.configurationId = mentionData.configId;
-                    }
-                    mentions.push(mention);
-                }
-            }
-            catch (error) {
-                console.warn('Failed to parse JSON mention:', match[0], error);
-                // Continue to next match
-            }
-        }
-        // If no JSON mentions found, fall back to legacy text format
-        if (mentions.length === 0) {
-            const legacyMatches = Array.from(text.matchAll(this.LEGACY_MENTION_REGEX));
-            for (const match of legacyMatches) {
-                // Extract the mention name (either quoted or unquoted)
-                const mentionName = match[1] || match[2];
-                if (!mentionName)
-                    continue;
-                // Try to match against agents first
-                const agent = this.findAgent(mentionName, availableAgents);
-                if (agent) {
-                    mentions.push({
-                        type: 'agent',
-                        id: agent.ID,
-                        name: agent.Name || 'Unknown'
-                    });
-                    continue;
-                }
-                // Try to match against users
-                if (availableUsers) {
-                    const user = this.findUser(mentionName, availableUsers);
-                    if (user) {
-                        mentions.push({
-                            type: 'user',
-                            id: user.ID,
-                            name: user.Name
-                        });
-                    }
-                }
-            }
-        }
-        // Extract first agent mention and all user mentions
-        const agentMention = mentions.find(m => m.type === 'agent') || null;
-        const userMentions = mentions.filter(m => m.type === 'user');
-        return {
-            mentions,
-            agentMention,
-            userMentions
-        };
-    }
-    /**
-     * Find an agent by name (case-insensitive)
-     * Uses exact match or starts-with match (no contains match to avoid ambiguity)
-     */
-    findAgent(name, agents) {
-        // Remove trailing punctuation and trim
-        const cleanName = name.replace(/[.,;!?]+$/, '').trim();
-        const lowerName = cleanName.toLowerCase();
-        // Try exact match first
-        let agent = agents.find(a => (a.Name?.toLowerCase() || '') === lowerName);
-        if (agent) {
-            return agent;
-        }
-        // Try starts with match
-        agent = agents.find(a => (a.Name?.toLowerCase() || '').startsWith(lowerName));
-        if (agent) {
-            return agent;
-        }
-        return null;
-        // Note: Removed "contains" match to avoid ambiguous matches
-        // e.g., "@Agent" would match multiple agents like "Marketing Agent", "Data Agent"
-        // Future: Could add LLM-based disambiguation as fallback
+    constructor(_bootstrap) {
+        // Injecting the bootstrap forces adapter registration on first construction.
     }
-    /**
-     * Find a user by name (case-insensitive)
-     * Uses exact match, email match, or starts-with match (no contains match to avoid ambiguity)
-     */
-    findUser(name, users) {
-        const lowerName = name.toLowerCase().trim();
-        // Try exact match first
-        let user = users.find(u => u.Name.toLowerCase() === lowerName);
-        if (user)
-            return user;
-        // Try email match
-        user = users.find(u => u.Email?.toLowerCase() === lowerName);
-        if (user)
-            return user;
-        // Try starts with match
-        user = users.find(u => u.Name.toLowerCase().startsWith(lowerName));
-        return user || null;
-        // Note: Removed "contains" match for consistency with agent matching
+    /** Pass-through to {@link ConversationsRuntime.Instance.Mentions.parseMentions}. */
+    parseMentions(text, availableAgents, availableUsers) {
+        return ConversationsRuntime.Instance.Mentions.parseMentions(text, availableAgents, availableUsers);
     }
-    /**
-     * Validate mentions - check if all mentions are valid
-     * Returns array of invalid mention names
-     * Supports both JSON and legacy mention formats
-     */
+    /** Pass-through to {@link ConversationsRuntime.Instance.Mentions.validateMentions}. */
     validateMentions(text, availableAgents, availableUsers) {
-        const invalidMentions = [];
-        // Check JSON mentions first
-        const jsonMatches = Array.from(text.matchAll(this.JSON_MENTION_REGEX));
-        if (jsonMatches.length > 0) {
-            for (const match of jsonMatches) {
-                try {
-                    const jsonStr = match[0].substring(1);
-                    const mentionData = JSON.parse(jsonStr);
-                    const mentionName = mentionData.name;
-                    if (mentionData.type === 'agent') {
-                        const isAgent = this.findAgent(mentionName, availableAgents) !== null;
-                        if (!isAgent) {
-                            invalidMentions.push(mentionName);
-                        }
-                    }
-                    else if (mentionData.type === 'user') {
-                        const isUser = availableUsers ? this.findUser(mentionName, availableUsers) !== null : false;
-                        if (!isUser) {
-                            invalidMentions.push(mentionName);
-                        }
-                    }
-                }
-                catch (error) {
-                    // Invalid JSON mention
-                    invalidMentions.push(match[0]);
-                }
-            }
-        }
-        else {
-            // Fall back to legacy format
-            const matches = Array.from(text.matchAll(this.LEGACY_MENTION_REGEX));
-            for (const match of matches) {
-                const mentionName = match[1] || match[2];
-                if (!mentionName)
-                    continue;
-                const isAgent = this.findAgent(mentionName, availableAgents) !== null;
-                const isUser = availableUsers ? this.findUser(mentionName, availableUsers) !== null : false;
-                if (!isAgent && !isUser) {
-                    invalidMentions.push(mentionName);
-                }
-            }
-        }
-        return invalidMentions;
+        return ConversationsRuntime.Instance.Mentions.validateMentions(text, availableAgents, availableUsers);
     }
-    /**
-     * Extract all mention names from text (raw strings)
-     * Supports both JSON and legacy mention formats
-     */
+    /** Pass-through to {@link ConversationsRuntime.Instance.Mentions.extractMentionNames}. */
     extractMentionNames(text) {
-        // Check JSON mentions first
-        const jsonMatches = Array.from(text.matchAll(this.JSON_MENTION_REGEX));
-        if (jsonMatches.length > 0) {
-            return jsonMatches.map(match => {
-                try {
-                    const jsonStr = match[0].substring(1);
-                    const mentionData = JSON.parse(jsonStr);
-                    return mentionData.name;
-                }
-                catch (error) {
-                    return '';
-                }
-            }).filter(Boolean);
-        }
-        // Fall back to legacy format
-        const matches = Array.from(text.matchAll(this.LEGACY_MENTION_REGEX));
-        return matches.map(match => match[1] || match[2]).filter(Boolean);
+        return ConversationsRuntime.Instance.Mentions.extractMentionNames(text);
     }
-    /**
-     * Replace mentions in text with formatted versions
-     * Example: "@agent" -> "@Agent Name" (with proper casing)
-     */
+    /** Pass-through to {@link ConversationsRuntime.Instance.Mentions.formatMentions}. */
     formatMentions(text, mentions) {
-        let formattedText = text;
-        for (const mention of mentions) {
-            // Find the mention in the text and replace with proper name
-            const patterns = [
-                new RegExp(`@"${mention.name}"`, 'gi'),
-                new RegExp(`@${mention.name.replace(/\s+/g, '\\s*')}`, 'gi')
-            ];
-            for (const pattern of patterns) {
-                formattedText = formattedText.replace(pattern, `@${mention.name}`);
-            }
-        }
-        return formattedText;
+        return ConversationsRuntime.Instance.Mentions.formatMentions(text, mentions);
     }
-    /**
-     * Convert a message with JSON-encoded mentions to plain text.
-     * Replaces @{...} JSON mentions with simple @Name format.
-     * This is a wrapper around ConversationUtility.ToPlainText() for Angular injection.
-     *
-     * @param text - The message text containing JSON mentions
-     * @param agents - Optional array of agents for name lookup
-     * @param users - Optional array of users for name lookup
-     * @returns Plain text with mentions converted to @Name format
-     *
-     * @example
-     * // Input: '@{"type":"agent","id":"123","name":"Sage"} help me'
-     * // Output: '@Sage help me'
-     */
+    /** Pass-through to {@link ConversationsRuntime.Instance.Mentions.toPlainText}. */
     toPlainText(text, agents, users) {
-        if (!text)
-            return '';
-        // Convert agents to the AgentInfo format expected by ConversationUtility
-        const agentInfos = agents?.map(a => ({
-            ID: a.ID,
-            Name: a.Name || 'Unknown'
-        }));
-        // Convert users to the UserInfo format expected by ConversationUtility
-        const userInfos = users?.map(u => ({
-            ID: u.ID,
-            Name: u.Name
-        }));
-        return ConversationUtility.ToPlainText(text, agentInfos, userInfos);
+        return ConversationsRuntime.Instance.Mentions.toPlainText(text, agents, users);
     }
-    static ɵfac = function MentionParserService_Factory(__ngFactoryType__) { return new (__ngFactoryType__ || MentionParserService)(); };
+    static ɵfac = function MentionParserService_Factory(__ngFactoryType__) { return new (__ngFactoryType__ || MentionParserService)(i0.ɵɵinject(i1.ConversationsRuntimeBootstrap)); };
     static ɵprov = /*@__PURE__*/ i0.ɵɵdefineInjectable({ token: MentionParserService, factory: MentionParserService.ɵfac, providedIn: 'root' });
 }
 (() => { (typeof ngDevMode === "undefined" || ngDevMode) && i0.ɵsetClassMetadata(MentionParserService, [{
         type: Injectable,
-        args: [{
-                providedIn: 'root'
-            }]
-    }], () => [], null); })();
+        args: [{ providedIn: 'root' }]
+    }], () => [{ type: i1.ConversationsRuntimeBootstrap }], null); })();
 //# sourceMappingURL=mention-parser.service.js.map

package/dist/lib/services/mention-parser.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"mention-parser.service.js","sourceRoot":"","sources":["../../../src/lib/services/mention-parser.service.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAE3C,OAAO,EAA2B,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;;AAG5F;;;GAGG;AAIH,MAAM,OAAO,oBAAoB;IAC/B,oGAAoG;IACnF,kBAAkB,GAAG,aAAa,CAAC;IACpD,sGAAsG;IACrF,oBAAoB,GAAG,oBAAoB,CAAC;IAE7D,gBAAe,CAAC;IAEhB;;;;;;;OAOG;IACH,aAAa,CACX,IAAY,EACZ,eAA0C,EAC1C,cAA2B;QAE3B,MAAM,QAAQ,GAAc,EAAE,CAAC;QAE/B,iDAAiD;QACjD,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;QAEvE,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;YAChC,IAAI,CAAC;gBACH,wCAAwC;gBACxC,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,aAAa;gBACpD,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;gBAExC,2BAA2B;gBAC3B,IAAI,WAAW,CAAC,IAAI,IAAI,WAAW,CAAC,EAAE,IAAI,WAAW,CAAC,IAAI,EAAE,CAAC;oBAC3D,MAAM,OAAO,GAAY;wBACvB,IAAI,EAAE,WAAW,CAAC,IAAI;wBACtB,EAAE,EAAE,WAAW,CAAC,EAAE;wBAClB,IAAI,EAAE,WAAW,CAAC,IAAI;qBACvB,CAAC;oBAEF,4CAA4C;oBAC5C,IAAI,WAAW,CAAC,QAAQ,EAAE,CAAC;wBACzB,OAAO,CAAC,eAAe,GAAG,WAAW,CAAC,QAAQ,CAAC;oBACjD,CAAC;oBAED,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACzB,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,IAAI,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;gBAC/D,yBAAyB;YAC3B,CAAC;QACH,CAAC;QAED,6DAA6D;QAC7D,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,MAAM,aAAa,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;YAE3E,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;gBAClC,uDAAuD;gBACvD,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;gBACzC,IAAI,CAAC,WAAW;oBAAE,SAAS;gBAE3B,oCAAoC;gBACpC,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC;gBAC3D,IAAI,KAAK,EAAE,CAAC;oBACV,QAAQ,CAAC,IAAI,CAAC;wBACZ,IAAI,EAAE,OAAO;wBACb,EAAE,EAAE,KAAK,CAAC,EAAE;wBACZ,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,SAAS;qBAC9B,CAAC,CAAC;oBACH,SAAS;gBACX,CAAC;gBAED,6BAA6B;gBAC7B,IAAI,cAAc,EAAE,CAAC;oBACnB,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC,CAAC;oBACxD,IAAI,IAAI,EAAE,CAAC;wBACT,QAAQ,CAAC,IAAI,CAAC;4BACZ,IAAI,EAAE,MAAM;4BACZ,EAAE,EAAE,IAAI,CAAC,EAAE;4BACX,IAAI,EAAE,IAAI,CAAC,IAAI;yBAChB,CAAC,CAAC;oBACL,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;QAED,oDAAoD;QACpD,MAAM,YAAY,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,IAAI,IAAI,CAAC;QACpE,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;QAE7D,OAAO;YACL,QAAQ;YACR,YAAY;YACZ,YAAY;SACb,CAAC;IACJ,CAAC;IAED;;;OAGG;IACK,SAAS,CAAC,IAAY,EAAE,MAAiC;QAC/D,uCAAuC;QACvC,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACvD,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;QAE1C,wBAAwB;QACxB,IAAI,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,KAAK,SAAS,CAAC,CAAC;QAC1E,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,KAAK,CAAC;QACf,CAAC;QAED,wBAAwB;QACxB,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;QAC9E,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,KAAK,CAAC;QACf,CAAC;QAED,OAAO,IAAI,CAAC;QAEZ,4DAA4D;QAC5D,kFAAkF;QAClF,yDAAyD;IAC3D,CAAC;IAED;;;OAGG;IACK,QAAQ,CAAC,IAAY,EAAE,KAAiB;QAC9C,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,IAAI,EAAE,CAAC;QAE5C,wBAAwB;QACxB,IAAI,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,SAAS,CAAC,CAAC;QAC/D,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QAEtB,kBAAkB;QAClB,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,KAAK,SAAS,CAAC,CAAC;QAC7D,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QAEtB,wBAAwB;QACxB,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;QACnE,OAAO,IAAI,IAAI,IAAI,CAAC;QAEpB,qEAAqE;IACvE,CAAC;IAED;;;;OAIG;IACH,gBAAgB,CACd,IAAY,EACZ,eAA0C,EAC1C,cAA2B;QAE3B,MAAM,eAAe,GAAa,EAAE,CAAC;QAErC,4BAA4B;QAC5B,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;QACvE,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,KAAK,MAAM,KAAK,IAAI,WAAW,EAAE,CAAC;gBAChC,IAAI,CAAC;oBACH,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;oBACtC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;oBACxC,MAAM,WAAW,GAAG,WAAW,CAAC,IAAI,CAAC;oBAErC,IAAI,WAAW,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;wBACjC,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,eAAe,CAAC,KAAK,IAAI,CAAC;wBACtE,IAAI,CAAC,OAAO,EAAE,CAAC;4BACb,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;wBACpC,CAAC;oBACH,CAAC;yBAAM,IAAI,WAAW,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;wBACvC,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;wBAC5F,IAAI,CAAC,MAAM,EAAE,CAAC;4BACZ,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;wBACpC,CAAC;oBACH,CAAC;gBACH,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,uBAAuB;oBACvB,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;gBACjC,CAAC;YACH,CAAC;QACH,CAAC;aAAM,CAAC;YACN,6BAA6B;YAC7B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;YAErE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,MAAM,WAAW,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC;gBACzC,IAAI,CAAC,WAAW;oBAAE,SAAS;gBAE3B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,EAAE,eAAe,CAAC,KAAK,IAAI,CAAC;gBACtE,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,WAAW,EAAE,cAAc,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;gBAE5F,IAAI,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,CAAC;oBACxB,eAAe,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;QACH,CAAC;QAED,OAAO,eAAe,CAAC;IACzB,CAAC;IAED;;;OAGG;IACH,mBAAmB,CAAC,IAAY;QAC9B,4BAA4B;QAC5B,MAAM,WAAW,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;QACvE,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,OAAO,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE;gBAC7B,IAAI,CAAC;oBACH,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;oBACtC,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;oBACxC,OAAO,WAAW,CAAC,IAAI,CAAC;gBAC1B,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,OAAO,EAAE,CAAC;gBACZ,CAAC;YACH,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACrB,CAAC;QAED,6BAA6B;QAC7B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,CAAC;QACrE,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACpE,CAAC;IAED;;;OAGG;IACH,cAAc,CACZ,IAAY,EACZ,QAAmB;QAEnB,IAAI,aAAa,GAAG,IAAI,CAAC;QAEzB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,4DAA4D;YAC5D,MAAM,QAAQ,GAAG;gBACf,IAAI,MAAM,CAAC,KAAK,OAAO,CAAC,IAAI,GAAG,EAAE,IAAI,CAAC;gBACtC,IAAI,MAAM,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,EAAE,IAAI,CAAC;aAC7D,CAAC;YAEF,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;gBAC/B,aAAa,GAAG,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;YACrE,CAAC;QACH,CAAC;QAED,OAAO,aAAa,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;OAaG;IACH,WAAW,CACT,IAAY,EACZ,MAAkC,EAClC,KAAkB;QAElB,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,CAAC;QAErB,yEAAyE;QACzE,MAAM,UAAU,GAAG,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACnC,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI,IAAI,SAAS;SAC1B,CAAC,CAAC,CAAC;QAEJ,uEAAuE;QACvE,MAAM,SAAS,GAAG,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACjC,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,IAAI,EAAE,CAAC,CAAC,IAAI;SACb,CAAC,CAAC,CAAC;QAEJ,OAAO,mBAAmB,CAAC,WAAW,CAAC,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC;IACtE,CAAC;8GAhSU,oBAAoB;gEAApB,oBAAoB,WAApB,oBAAoB,mBAFnB,MAAM;;iFAEP,oBAAoB;cAHhC,UAAU;eAAC;gBACV,UAAU,EAAE,MAAM;aACnB","sourcesContent":["import { Injectable } from '@angular/core';\nimport { Mention, MentionParseResult } from '../models/conversation-state.model';\nimport { MJAIAgentEntityExtended, ConversationUtility } from '@memberjunction/ai-core-plus';\nimport { UserInfo } from '@memberjunction/core';\n\n/**\n * Service for parsing @mentions from message text\n * Supports both JSON format and legacy text format\n */\n@Injectable({\n  providedIn: 'root'\n})\nexport class MentionParserService {\n  // Regex to match JSON mentions: @{type:\"agent\",id:\"uuid\",name:\"Name\",configId:\"uuid\",config:\"High\"}\n  private readonly JSON_MENTION_REGEX = /@\\{[^}]+\\}/g;\n  // Regex to match legacy @mentions - supports names with spaces if quoted: @\"Agent Name\" or @AgentName\n  private readonly LEGACY_MENTION_REGEX = /@\"([^\"]+)\"|@(\\S+)/g;\n\n  constructor() {}\n\n  /**\n   * Parse mentions from message text\n   * Supports both JSON format (@{type:\"agent\",id:\"uuid\",...}) and legacy text format (@AgentName)\n   * @param text The message text to parse\n   * @param availableAgents List of available agents for matching\n   * @param availableUsers List of available users for matching (optional)\n   * @returns Parsed mentions with agent and user separation\n   */\n  parseMentions(\n    text: string,\n    availableAgents: MJAIAgentEntityExtended[],\n    availableUsers?: UserInfo[]\n  ): MentionParseResult {\n    const mentions: Mention[] = [];\n\n    // First, try to parse JSON mentions (new format)\n    const jsonMatches = Array.from(text.matchAll(this.JSON_MENTION_REGEX));\n\n    for (const match of jsonMatches) {\n      try {\n        // Extract JSON string (remove @ prefix)\n        const jsonStr = match[0].substring(1); // Remove '@'\n        const mentionData = JSON.parse(jsonStr);\n\n        // Validate required fields\n        if (mentionData.type && mentionData.id && mentionData.name) {\n          const mention: Mention = {\n            type: mentionData.type,\n            id: mentionData.id,\n            name: mentionData.name\n          };\n\n          // Add configuration if present (for agents)\n          if (mentionData.configId) {\n            mention.configurationId = mentionData.configId;\n          }\n\n          mentions.push(mention);\n        }\n      } catch (error) {\n        console.warn('Failed to parse JSON mention:', match[0], error);\n        // Continue to next match\n      }\n    }\n\n    // If no JSON mentions found, fall back to legacy text format\n    if (mentions.length === 0) {\n      const legacyMatches = Array.from(text.matchAll(this.LEGACY_MENTION_REGEX));\n\n      for (const match of legacyMatches) {\n        // Extract the mention name (either quoted or unquoted)\n        const mentionName = match[1] || match[2];\n        if (!mentionName) continue;\n\n        // Try to match against agents first\n        const agent = this.findAgent(mentionName, availableAgents);\n        if (agent) {\n          mentions.push({\n            type: 'agent',\n            id: agent.ID,\n            name: agent.Name || 'Unknown'\n          });\n          continue;\n        }\n\n        // Try to match against users\n        if (availableUsers) {\n          const user = this.findUser(mentionName, availableUsers);\n          if (user) {\n            mentions.push({\n              type: 'user',\n              id: user.ID,\n              name: user.Name\n            });\n          }\n        }\n      }\n    }\n\n    // Extract first agent mention and all user mentions\n    const agentMention = mentions.find(m => m.type === 'agent') || null;\n    const userMentions = mentions.filter(m => m.type === 'user');\n\n    return {\n      mentions,\n      agentMention,\n      userMentions\n    };\n  }\n\n  /**\n   * Find an agent by name (case-insensitive)\n   * Uses exact match or starts-with match (no contains match to avoid ambiguity)\n   */\n  private findAgent(name: string, agents: MJAIAgentEntityExtended[]): MJAIAgentEntityExtended | null {\n    // Remove trailing punctuation and trim\n    const cleanName = name.replace(/[.,;!?]+$/, '').trim();\n    const lowerName = cleanName.toLowerCase();\n\n    // Try exact match first\n    let agent = agents.find(a => (a.Name?.toLowerCase() || '') === lowerName);\n    if (agent) {\n      return agent;\n    }\n\n    // Try starts with match\n    agent = agents.find(a => (a.Name?.toLowerCase() || '').startsWith(lowerName));\n    if (agent) {\n      return agent;\n    }\n\n    return null;\n\n    // Note: Removed \"contains\" match to avoid ambiguous matches\n    // e.g., \"@Agent\" would match multiple agents like \"Marketing Agent\", \"Data Agent\"\n    // Future: Could add LLM-based disambiguation as fallback\n  }\n\n  /**\n   * Find a user by name (case-insensitive)\n   * Uses exact match, email match, or starts-with match (no contains match to avoid ambiguity)\n   */\n  private findUser(name: string, users: UserInfo[]): UserInfo | null {\n    const lowerName = name.toLowerCase().trim();\n\n    // Try exact match first\n    let user = users.find(u => u.Name.toLowerCase() === lowerName);\n    if (user) return user;\n\n    // Try email match\n    user = users.find(u => u.Email?.toLowerCase() === lowerName);\n    if (user) return user;\n\n    // Try starts with match\n    user = users.find(u => u.Name.toLowerCase().startsWith(lowerName));\n    return user || null;\n\n    // Note: Removed \"contains\" match for consistency with agent matching\n  }\n\n  /**\n   * Validate mentions - check if all mentions are valid\n   * Returns array of invalid mention names\n   * Supports both JSON and legacy mention formats\n   */\n  validateMentions(\n    text: string,\n    availableAgents: MJAIAgentEntityExtended[],\n    availableUsers?: UserInfo[]\n  ): string[] {\n    const invalidMentions: string[] = [];\n\n    // Check JSON mentions first\n    const jsonMatches = Array.from(text.matchAll(this.JSON_MENTION_REGEX));\n    if (jsonMatches.length > 0) {\n      for (const match of jsonMatches) {\n        try {\n          const jsonStr = match[0].substring(1);\n          const mentionData = JSON.parse(jsonStr);\n          const mentionName = mentionData.name;\n\n          if (mentionData.type === 'agent') {\n            const isAgent = this.findAgent(mentionName, availableAgents) !== null;\n            if (!isAgent) {\n              invalidMentions.push(mentionName);\n            }\n          } else if (mentionData.type === 'user') {\n            const isUser = availableUsers ? this.findUser(mentionName, availableUsers) !== null : false;\n            if (!isUser) {\n              invalidMentions.push(mentionName);\n            }\n          }\n        } catch (error) {\n          // Invalid JSON mention\n          invalidMentions.push(match[0]);\n        }\n      }\n    } else {\n      // Fall back to legacy format\n      const matches = Array.from(text.matchAll(this.LEGACY_MENTION_REGEX));\n\n      for (const match of matches) {\n        const mentionName = match[1] || match[2];\n        if (!mentionName) continue;\n\n        const isAgent = this.findAgent(mentionName, availableAgents) !== null;\n        const isUser = availableUsers ? this.findUser(mentionName, availableUsers) !== null : false;\n\n        if (!isAgent && !isUser) {\n          invalidMentions.push(mentionName);\n        }\n      }\n    }\n\n    return invalidMentions;\n  }\n\n  /**\n   * Extract all mention names from text (raw strings)\n   * Supports both JSON and legacy mention formats\n   */\n  extractMentionNames(text: string): string[] {\n    // Check JSON mentions first\n    const jsonMatches = Array.from(text.matchAll(this.JSON_MENTION_REGEX));\n    if (jsonMatches.length > 0) {\n      return jsonMatches.map(match => {\n        try {\n          const jsonStr = match[0].substring(1);\n          const mentionData = JSON.parse(jsonStr);\n          return mentionData.name;\n        } catch (error) {\n          return '';\n        }\n      }).filter(Boolean);\n    }\n\n    // Fall back to legacy format\n    const matches = Array.from(text.matchAll(this.LEGACY_MENTION_REGEX));\n    return matches.map(match => match[1] || match[2]).filter(Boolean);\n  }\n\n  /**\n   * Replace mentions in text with formatted versions\n   * Example: \"@agent\" -> \"@Agent Name\" (with proper casing)\n   */\n  formatMentions(\n    text: string,\n    mentions: Mention[]\n  ): string {\n    let formattedText = text;\n\n    for (const mention of mentions) {\n      // Find the mention in the text and replace with proper name\n      const patterns = [\n        new RegExp(`@\"${mention.name}\"`, 'gi'),\n        new RegExp(`@${mention.name.replace(/\\s+/g, '\\\\s*')}`, 'gi')\n      ];\n\n      for (const pattern of patterns) {\n        formattedText = formattedText.replace(pattern, `@${mention.name}`);\n      }\n    }\n\n    return formattedText;\n  }\n\n  /**\n   * Convert a message with JSON-encoded mentions to plain text.\n   * Replaces @{...} JSON mentions with simple @Name format.\n   * This is a wrapper around ConversationUtility.ToPlainText() for Angular injection.\n   *\n   * @param text - The message text containing JSON mentions\n   * @param agents - Optional array of agents for name lookup\n   * @param users - Optional array of users for name lookup\n   * @returns Plain text with mentions converted to @Name format\n   *\n   * @example\n   * // Input: '@{\"type\":\"agent\",\"id\":\"123\",\"name\":\"Sage\"} help me'\n   * // Output: '@Sage help me'\n   */\n  toPlainText(\n    text: string,\n    agents?: MJAIAgentEntityExtended[],\n    users?: UserInfo[]\n  ): string {\n    if (!text) return '';\n\n    // Convert agents to the AgentInfo format expected by ConversationUtility\n    const agentInfos = agents?.map(a => ({\n      ID: a.ID,\n      Name: a.Name || 'Unknown'\n    }));\n\n    // Convert users to the UserInfo format expected by ConversationUtility\n    const userInfos = users?.map(u => ({\n      ID: u.ID,\n      Name: u.Name\n    }));\n\n    return ConversationUtility.ToPlainText(text, agentInfos, userInfos);\n  }\n}\n"]}
+{"version":3,"file":"mention-parser.service.js","sourceRoot":"","sources":["../../../src/lib/services/mention-parser.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,uCAAuC,CAAC;;;AAO7E,gFAAgF;AAChF,kFAAkF;AAClF,6EAA6E;AAC7E,8EAA8E;AAG9E,MAAM,OAAO,oBAAoB;IAC7B,YAAY,UAAyC;QACjD,6EAA6E;IACjF,CAAC;IAED,oFAAoF;IACpF,aAAa,CACT,IAAY,EACZ,eAA0C,EAC1C,cAA2B;QAE3B,OAAO,oBAAoB,CAAC,QAAQ,CAAC,QAAQ,CAAC,aAAa,CACvD,IAAI,EACJ,eAAe,EACf,cAAc,CACjB,CAAC;IACN,CAAC;IAED,uFAAuF;IACvF,gBAAgB,CACZ,IAAY,EACZ,eAA0C,EAC1C,cAA2B;QAE3B,OAAO,oBAAoB,CAAC,QAAQ,CAAC,QAAQ,CAAC,gBAAgB,CAC1D,IAAI,EACJ,eAAe,EACf,cAAc,CACjB,CAAC;IACN,CAAC;IAED,0FAA0F;IAC1F,mBAAmB,CAAC,IAAY;QAC5B,OAAO,oBAAoB,CAAC,QAAQ,CAAC,QAAQ,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC5E,CAAC;IAED,qFAAqF;IACrF,cAAc,CAAC,IAAY,EAAE,QAAmB;QAC5C,OAAO,oBAAoB,CAAC,QAAQ,CAAC,QAAQ,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACjF,CAAC;IAED,kFAAkF;IAClF,WAAW,CACP,IAAY,EACZ,MAAkC,EAClC,KAAkB;QAElB,OAAO,oBAAoB,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACnF,CAAC;8GAhDQ,oBAAoB;gEAApB,oBAAoB,WAApB,oBAAoB,mBADP,MAAM;;iFACnB,oBAAoB;cADhC,UAAU;eAAC,EAAE,UAAU,EAAE,MAAM,EAAE","sourcesContent":["/**\n * @fileoverview Angular DI shim over the framework-agnostic `MentionParser` from\n * `@memberjunction/conversations-runtime`.\n *\n * Previously this service owned the regex-based mention-parsing logic. That logic\n * moved into the runtime in PR 1; this file is now a thin pass-through so existing\n * `inject(MentionParserService)` call sites keep working without changes.\n *\n * **For new code:** prefer `ConversationsRuntime.Instance.Mentions` directly.\n */\n\nimport { Injectable } from '@angular/core';\nimport { ConversationsRuntime } from '@memberjunction/conversations-runtime';\nimport type { Mention, MentionParseResult } from '@memberjunction/conversations-runtime';\nimport { MJAIAgentEntityExtended } from '@memberjunction/ai-core-plus';\nimport { UserInfo } from '@memberjunction/core';\n\nimport { ConversationsRuntimeBootstrap } from './conversations-runtime-bootstrap.service';\n\n// NOTE: `Mention` and `MentionParseResult` are NOT re-exported from this file —\n// the model's `conversation-state.model.ts` already exports `MentionParseResult`,\n// and re-exporting here causes a public-api ambiguity. Consumers wanting the\n// runtime's types should import from `@memberjunction/conversations-runtime`.\n\n@Injectable({ providedIn: 'root' })\nexport class MentionParserService {\n    constructor(_bootstrap: ConversationsRuntimeBootstrap) {\n        // Injecting the bootstrap forces adapter registration on first construction.\n    }\n\n    /** Pass-through to {@link ConversationsRuntime.Instance.Mentions.parseMentions}. */\n    parseMentions(\n        text: string,\n        availableAgents: MJAIAgentEntityExtended[],\n        availableUsers?: UserInfo[]\n    ): MentionParseResult {\n        return ConversationsRuntime.Instance.Mentions.parseMentions(\n            text,\n            availableAgents,\n            availableUsers\n        );\n    }\n\n    /** Pass-through to {@link ConversationsRuntime.Instance.Mentions.validateMentions}. */\n    validateMentions(\n        text: string,\n        availableAgents: MJAIAgentEntityExtended[],\n        availableUsers?: UserInfo[]\n    ): string[] {\n        return ConversationsRuntime.Instance.Mentions.validateMentions(\n            text,\n            availableAgents,\n            availableUsers\n        );\n    }\n\n    /** Pass-through to {@link ConversationsRuntime.Instance.Mentions.extractMentionNames}. */\n    extractMentionNames(text: string): string[] {\n        return ConversationsRuntime.Instance.Mentions.extractMentionNames(text);\n    }\n\n    /** Pass-through to {@link ConversationsRuntime.Instance.Mentions.formatMentions}. */\n    formatMentions(text: string, mentions: Mention[]): string {\n        return ConversationsRuntime.Instance.Mentions.formatMentions(text, mentions);\n    }\n\n    /** Pass-through to {@link ConversationsRuntime.Instance.Mentions.toPlainText}. */\n    toPlainText(\n        text: string,\n        agents?: MJAIAgentEntityExtended[],\n        users?: UserInfo[]\n    ): string {\n        return ConversationsRuntime.Instance.Mentions.toPlainText(text, agents, users);\n    }\n}\n"]}

package/dist/lib/services/narration-template.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Pure helpers for building the one-off spoken progress-narration instructions a
+ * realtime voice session sends to the model while delegated work runs.
+ *
+ * The instruction text is DB-driven: the server resolves the `Realtime Co-Agent - Progress Narration`
+ * prompt's `TemplateText` at session start and threads it to the browser. The template may use:
+ *   - `{{ progressMessage }}`  — the aggregated progress digest (one or more updates, oldest first)
+ *   - `{{ priorNarrations }}`  — what the model has ALREADY said aloud for this task (so it can
+ *                                continue the story instead of repeating itself)
+ *   - `{{ updateNumber }}`     — 1-based count of spoken updates for this task
+ * When a deployment hasn't synced that prompt yet, the built-in
+ * {@link DefaultNarrationInstructions} fallback keeps narration working with the same semantics.
+ */
+/** Options accompanying the progress digest when building narration instructions. */
+export interface NarrationBuildOptions {
+    /** The narration utterances the model has already spoken for this task, oldest first. */
+    PriorNarrations?: string[];
+    /** 1-based number of this spoken update within the current task. */
+    UpdateNumber?: number;
+}
+/**
+ * Builds the built-in (fallback) narration instructions — same semantics as the DB template:
+ * first person, varied phrasing that continues from what was already said, no repeats.
+ *
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param options Prior narrations + update number for phrasing variation/chaining.
+ * @returns The complete spoken-update instruction text.
+ */
+export declare function DefaultNarrationInstructions(digest: string, options?: NarrationBuildOptions): string;
+/**
+ * Builds the narration instructions from the server-provided template by substituting
+ * `{{ progressMessage }}`, `{{ priorNarrations }}`, and `{{ updateNumber }}` (space and no-space
+ * variants). Falls back to {@link DefaultNarrationInstructions} when the template is absent or
+ * blank (deployments that haven't synced the narration prompt).
+ *
+ * @param template The DB-driven instruction template, or `null`/`undefined` when unavailable.
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param options Prior narrations + update number for phrasing variation/chaining.
+ * @returns The complete spoken-update instruction text.
+ */
+export declare function BuildNarrationInstructions(template: string | null | undefined, digest: string, options?: NarrationBuildOptions): string;
+//# sourceMappingURL=narration-template.d.ts.map

package/dist/lib/services/narration-template.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"narration-template.d.ts","sourceRoot":"","sources":["../../../src/lib/services/narration-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,qFAAqF;AACrF,MAAM,WAAW,qBAAqB;IACpC,yFAAyF;IACzF,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,oEAAoE;IACpE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAuBD;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAcpG;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,0BAA0B,CACxC,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACnC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,qBAAqB,GAC9B,MAAM,CAQR"}

package/dist/lib/services/narration-template.js

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Pure helpers for building the one-off spoken progress-narration instructions a
+ * realtime voice session sends to the model while delegated work runs.
+ *
+ * The instruction text is DB-driven: the server resolves the `Realtime Co-Agent - Progress Narration`
+ * prompt's `TemplateText` at session start and threads it to the browser. The template may use:
+ *   - `{{ progressMessage }}`  — the aggregated progress digest (one or more updates, oldest first)
+ *   - `{{ priorNarrations }}`  — what the model has ALREADY said aloud for this task (so it can
+ *                                continue the story instead of repeating itself)
+ *   - `{{ updateNumber }}`     — 1-based count of spoken updates for this task
+ * When a deployment hasn't synced that prompt yet, the built-in
+ * {@link DefaultNarrationInstructions} fallback keeps narration working with the same semantics.
+ */
+const PROGRESS_TOKENS = ['{{ progressMessage }}', '{{progressMessage}}'];
+const PRIOR_TOKENS = ['{{ priorNarrations }}', '{{priorNarrations}}'];
+const NUMBER_TOKENS = ['{{ updateNumber }}', '{{updateNumber}}'];
+/** Replaces every occurrence of each token with the value. */
+function replaceTokens(text, tokens, value) {
+    let out = text;
+    for (const t of tokens) {
+        out = out.split(t).join(value);
+    }
+    return out;
+}
+/** Formats the prior spoken narrations for injection ("none yet" when this is the first update). */
+function formatPriorNarrations(prior) {
+    if (!prior || prior.length === 0) {
+        return 'Nothing yet — this is your first spoken update for this task.';
+    }
+    return prior.map((p) => `- "${p}"`).join('\n');
+}
+/**
+ * Builds the built-in (fallback) narration instructions — same semantics as the DB template:
+ * first person, varied phrasing that continues from what was already said, no repeats.
+ *
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param options Prior narrations + update number for phrasing variation/chaining.
+ * @returns The complete spoken-update instruction text.
+ */
+export function DefaultNarrationInstructions(digest, options) {
+    const updateNumber = options?.UpdateNumber ?? 1;
+    return (`Live progress on the work YOU are doing for the user (oldest first): ${digest}. ` +
+        `This is spoken update #${updateNumber} for this task. You have already told the user:\n` +
+        `${formatPriorNarrations(options?.PriorNarrations)}\n` +
+        `Say ONE short, natural sentence in the FIRST PERSON continuing the story of what you are doing. ` +
+        `For the first update something like "I'm pulling that up now" is fine; for later updates VARY the ` +
+        `phrasing and build on what you last said ("Got the first part — grabbing the rest", "Almost there, ` +
+        `just double-checking the numbers") instead of repeating an "I'm now…" pattern. Never repeat ` +
+        `information you've already conveyed — only add what's new. Strictly first person: the words "it" ` +
+        `and the agent's name must not be the subject of your sentence, and never say generic filler like ` +
+        `"it's still running in the background".`);
+}
+/**
+ * Builds the narration instructions from the server-provided template by substituting
+ * `{{ progressMessage }}`, `{{ priorNarrations }}`, and `{{ updateNumber }}` (space and no-space
+ * variants). Falls back to {@link DefaultNarrationInstructions} when the template is absent or
+ * blank (deployments that haven't synced the narration prompt).
+ *
+ * @param template The DB-driven instruction template, or `null`/`undefined` when unavailable.
+ * @param digest The aggregated progress digest (one or more updates, oldest first).
+ * @param options Prior narrations + update number for phrasing variation/chaining.
+ * @returns The complete spoken-update instruction text.
+ */
+export function BuildNarrationInstructions(template, digest, options) {
+    if (!template || template.trim().length === 0) {
+        return DefaultNarrationInstructions(digest, options);
+    }
+    let out = replaceTokens(template, PROGRESS_TOKENS, digest);
+    out = replaceTokens(out, PRIOR_TOKENS, formatPriorNarrations(options?.PriorNarrations));
+    out = replaceTokens(out, NUMBER_TOKENS, String(options?.UpdateNumber ?? 1));
+    return out;
+}
+//# sourceMappingURL=narration-template.js.map

package/dist/lib/services/narration-template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"narration-template.js","sourceRoot":"","sources":["../../../src/lib/services/narration-template.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,MAAM,eAAe,GAAG,CAAC,uBAAuB,EAAE,qBAAqB,CAAC,CAAC;AACzE,MAAM,YAAY,GAAG,CAAC,uBAAuB,EAAE,qBAAqB,CAAC,CAAC;AACtE,MAAM,aAAa,GAAG,CAAC,oBAAoB,EAAE,kBAAkB,CAAC,CAAC;AAEjE,8DAA8D;AAC9D,SAAS,aAAa,CAAC,IAAY,EAAE,MAAgB,EAAE,KAAa;IAClE,IAAI,GAAG,GAAG,IAAI,CAAC;IACf,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACjC,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,oGAAoG;AACpG,SAAS,qBAAqB,CAAC,KAA2B;IACxD,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,+DAA+D,CAAC;IACzE,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,4BAA4B,CAAC,MAAc,EAAE,OAA+B;IAC1F,MAAM,YAAY,GAAG,OAAO,EAAE,YAAY,IAAI,CAAC,CAAC;IAChD,OAAO,CACL,wEAAwE,MAAM,IAAI;QAClF,0BAA0B,YAAY,mDAAmD;QACzF,GAAG,qBAAqB,CAAC,OAAO,EAAE,eAAe,CAAC,IAAI;QACtD,kGAAkG;QAClG,oGAAoG;QACpG,qGAAqG;QACrG,8FAA8F;QAC9F,mGAAmG;QACnG,mGAAmG;QACnG,yCAAyC,CAC1C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CACxC,QAAmC,EACnC,MAAc,EACd,OAA+B;IAE/B,IAAI,CAAC,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9C,OAAO,4BAA4B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvD,CAAC;IACD,IAAI,GAAG,GAAG,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,MAAM,CAAC,CAAC;IAC3D,GAAG,GAAG,aAAa,CAAC,GAAG,EAAE,YAAY,EAAE,qBAAqB,CAAC,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC;IACxF,GAAG,GAAG,aAAa,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,CAAC,OAAO,EAAE,YAAY,IAAI,CAAC,CAAC,CAAC,CAAC;IAC5E,OAAO,GAAG,CAAC;AACb,CAAC","sourcesContent":["/**\n * @fileoverview Pure helpers for building the one-off spoken progress-narration instructions a\n * realtime voice session sends to the model while delegated work runs.\n *\n * The instruction text is DB-driven: the server resolves the `Realtime Co-Agent - Progress Narration`\n * prompt's `TemplateText` at session start and threads it to the browser. The template may use:\n *   - `{{ progressMessage }}`  — the aggregated progress digest (one or more updates, oldest first)\n *   - `{{ priorNarrations }}`  — what the model has ALREADY said aloud for this task (so it can\n *                                continue the story instead of repeating itself)\n *   - `{{ updateNumber }}`     — 1-based count of spoken updates for this task\n * When a deployment hasn't synced that prompt yet, the built-in\n * {@link DefaultNarrationInstructions} fallback keeps narration working with the same semantics.\n */\n\n/** Options accompanying the progress digest when building narration instructions. */\nexport interface NarrationBuildOptions {\n  /** The narration utterances the model has already spoken for this task, oldest first. */\n  PriorNarrations?: string[];\n  /** 1-based number of this spoken update within the current task. */\n  UpdateNumber?: number;\n}\n\nconst PROGRESS_TOKENS = ['{{ progressMessage }}', '{{progressMessage}}'];\nconst PRIOR_TOKENS = ['{{ priorNarrations }}', '{{priorNarrations}}'];\nconst NUMBER_TOKENS = ['{{ updateNumber }}', '{{updateNumber}}'];\n\n/** Replaces every occurrence of each token with the value. */\nfunction replaceTokens(text: string, tokens: string[], value: string): string {\n  let out = text;\n  for (const t of tokens) {\n    out = out.split(t).join(value);\n  }\n  return out;\n}\n\n/** Formats the prior spoken narrations for injection (\"none yet\" when this is the first update). */\nfunction formatPriorNarrations(prior: string[] | undefined): string {\n  if (!prior || prior.length === 0) {\n    return 'Nothing yet — this is your first spoken update for this task.';\n  }\n  return prior.map((p) => `- \"${p}\"`).join('\\n');\n}\n\n/**\n * Builds the built-in (fallback) narration instructions — same semantics as the DB template:\n * first person, varied phrasing that continues from what was already said, no repeats.\n *\n * @param digest The aggregated progress digest (one or more updates, oldest first).\n * @param options Prior narrations + update number for phrasing variation/chaining.\n * @returns The complete spoken-update instruction text.\n */\nexport function DefaultNarrationInstructions(digest: string, options?: NarrationBuildOptions): string {\n  const updateNumber = options?.UpdateNumber ?? 1;\n  return (\n    `Live progress on the work YOU are doing for the user (oldest first): ${digest}. ` +\n    `This is spoken update #${updateNumber} for this task. You have already told the user:\\n` +\n    `${formatPriorNarrations(options?.PriorNarrations)}\\n` +\n    `Say ONE short, natural sentence in the FIRST PERSON continuing the story of what you are doing. ` +\n    `For the first update something like \"I'm pulling that up now\" is fine; for later updates VARY the ` +\n    `phrasing and build on what you last said (\"Got the first part — grabbing the rest\", \"Almost there, ` +\n    `just double-checking the numbers\") instead of repeating an \"I'm now…\" pattern. Never repeat ` +\n    `information you've already conveyed — only add what's new. Strictly first person: the words \"it\" ` +\n    `and the agent's name must not be the subject of your sentence, and never say generic filler like ` +\n    `\"it's still running in the background\".`\n  );\n}\n\n/**\n * Builds the narration instructions from the server-provided template by substituting\n * `{{ progressMessage }}`, `{{ priorNarrations }}`, and `{{ updateNumber }}` (space and no-space\n * variants). Falls back to {@link DefaultNarrationInstructions} when the template is absent or\n * blank (deployments that haven't synced the narration prompt).\n *\n * @param template The DB-driven instruction template, or `null`/`undefined` when unavailable.\n * @param digest The aggregated progress digest (one or more updates, oldest first).\n * @param options Prior narrations + update number for phrasing variation/chaining.\n * @returns The complete spoken-update instruction text.\n */\nexport function BuildNarrationInstructions(\n  template: string | null | undefined,\n  digest: string,\n  options?: NarrationBuildOptions\n): string {\n  if (!template || template.trim().length === 0) {\n    return DefaultNarrationInstructions(digest, options);\n  }\n  let out = replaceTokens(template, PROGRESS_TOKENS, digest);\n  out = replaceTokens(out, PRIOR_TOKENS, formatPriorNarrations(options?.PriorNarrations));\n  out = replaceTokens(out, NUMBER_TOKENS, String(options?.UpdateNumber ?? 1));\n  return out;\n}\n"]}

package/dist/lib/services/realtime-pairing.d.ts

@@ -0,0 +1,120 @@
+import { IMetadataProvider } from '@memberjunction/core';
+/**
+ * The narrow read-only projection of an `MJ: AI Agent Co Agents` row the voice UI consumes
+ * (loaded via {@link LoadCoAgentPairings} from {@link AIEngineBase}'s cached `AgentCoAgents`;
+ * only **Active** rows of relationship **Type `'CoAgent'`** with a specific agent target —
+ * type-level rows express the resolution-chain default, not a target restriction, and
+ * reserved relationship types are ignored until their features ship). Pairing semantics: a
+ * co-agent with ZERO such rows is **universal** (it can front any target agent — the
+ * zero-config default); a co-agent WITH rows may front exactly the listed targets, with the
+ * `IsDefault` row as its preselected target.
+ */
+export interface RealtimePairedAgentRow {
+    /** The pairing row id. */
+    ID: string;
+    /** The Realtime-type co-agent the pairing belongs to. */
+    CoAgentID: string;
+    /** The target agent this co-agent may front. */
+    TargetAgentID: string;
+    /** Denormalized target-agent display name (from the base view). */
+    TargetAgent: string | null;
+    /** When true, this target is the co-agent's default (at most one per co-agent). */
+    IsDefault: boolean;
+    /** Display/list ordering of the pairing rows. */
+    Sequence: number | null;
+}
+/** Minimal agent shape the pure pairing/co-agent helpers operate on. */
+export interface RealtimeAgentLike {
+    ID: string;
+}
+/**
+ * Loads the pairing rows for one co-agent from {@link AIEngineBase}'s cached
+ * `MJ: AI Agent Co Agents` metadata (provider-scoped engine instance, lazy `Config`),
+ * in `Sequence` order. The engine's BaseEntity-event reactivity keeps the cache fresh —
+ * no per-call RunView round-trip.
+ *
+ * Tolerant by design: any failure degrades to an EMPTY list — i.e. "no pairing
+ * constraint". The client gate is pure disclosure; the server independently validates
+ * the co-agent/target pairing at session mint.
+ */
+export declare function LoadCoAgentPairings(provider: IMetadataProvider, coAgentId: string): Promise<RealtimePairedAgentRow[]>;
+/**
+ * Returns the pairing rows in canonical display order: `Sequence` ascending (null/missing
+ * sequences last), ties broken by target-agent name. Pure; never mutates the input.
+ */
+export declare function SortPairings(pairings: readonly RealtimePairedAgentRow[]): RealtimePairedAgentRow[];
+/**
+ * Applies the pairing constraint to a candidate target-agent list:
+ * - ZERO pairing rows → the co-agent is universal; the candidates are returned unchanged
+ *   (today's flow untouched).
+ * - One or more rows → only candidates that appear among the pairing targets are
+ *   returned, ordered by the pairings' `Sequence`. Paired targets the user can't see /
+ *   run (absent from `agents`) are silently dropped.
+ *
+ * Pure and UUID-casing safe (`NormalizeUUID` keys).
+ */
+export declare function ConstrainTargetsToPairings<T extends RealtimeAgentLike>(agents: readonly T[], pairings: readonly RealtimePairedAgentRow[]): T[];
+/**
+ * The co-agent's default target from its pairing rows — the first `IsDefault` row in
+ * `Sequence` order (server enforces at most one, but the helper stays deterministic
+ * regardless). `null` when there are no rows or none is marked default.
+ */
+export declare function DefaultPairedTargetId(pairings: readonly RealtimePairedAgentRow[]): string | null;
+/**
+ * Whether the pairing rows permit `targetAgentId` as a target. ZERO rows means the
+ * co-agent is universal (always allowed); otherwise the target must appear among the
+ * rows. Missing/empty target id is never allowed against a constrained co-agent.
+ */
+export declare function PairingsAllowTarget(pairings: readonly RealtimePairedAgentRow[], targetAgentId: string | null | undefined): boolean;
+/**
+ * Filters an agent list down to ACTIVE Realtime-type **co-agent** candidates. The input
+ * is expected to already be the run-permission-filtered active-agent set the host uses
+ * for routing/@mentions, so this only applies the agent-TYPE cut (trim +
+ * case-insensitive match on the denormalized `Type` name).
+ */
+export declare function FilterRealtimeCoAgents<T extends {
+    Type: string | null;
+}>(agents: readonly T[]): T[];
+/**
+ * A selectable realtime model option in the voice picker (narrow read-only projection of
+ * `MJ: AI Models` — only the fields the dropdown renders).
+ */
+export interface RealtimeModelOption {
+    /** The `MJ: AI Models` row id. */
+    ID: string;
+    /** The model's display name. */
+    Name: string;
+}
+/**
+ * The minimal `MJ: AI Models` row shape {@link BuildRealtimeModelOptions} consumes —
+ * structurally satisfied by `AIEngineBase`'s cached `Models` entities.
+ */
+export interface VoiceModelCandidate {
+    /** The `MJ: AI Models` row id. */
+    ID: string;
+    /** The model's display name. */
+    Name: string;
+    /** Denormalized model-type name (e.g. 'LLM', 'Realtime'). */
+    AIModelType: string | null;
+    /** Whether the model is active and selectable. */
+    IsActive: boolean;
+}
+/**
+ * Builds the "Voice model" dropdown options from a cached model list: ACTIVE models whose
+ * type is `Realtime` (trim + case-insensitive — SQL-collation parity with the previous
+ * `IsActive = 1 AND AIModelType = 'Realtime'` filter), projected to {@link RealtimeModelOption}
+ * and sorted by Name. Pure; never mutates the input.
+ */
+export declare function BuildRealtimeModelOptions(models: ReadonlyArray<VoiceModelCandidate>): RealtimeModelOption[];
+/**
+ * Builds the `configOverridesJson` payload for the `StartRealtimeClientSession` mint from
+ * what the (authorization-gated) pickers chose. Currently the only override is the
+ * explicit realtime model preference; the envelope shape —
+ * `{"realtime":{"modelPreference":"<id>"}}` — is the pinned server contract and is
+ * structured so future overrides ride alongside without reshaping.
+ *
+ * @returns The JSON string, or `null` when nothing was overridden (the common case —
+ *   `null` keeps the mint identical to today's behavior).
+ */
+export declare function BuildRealtimeConfigOverridesJson(preferredModelId: string | null | undefined): string | null;
+//# sourceMappingURL=realtime-pairing.d.ts.map

package/dist/lib/services/realtime-pairing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime-pairing.d.ts","sourceRoot":"","sources":["../../../src/lib/services/realtime-pairing.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAIzD;;;;;;;;;GASG;AACH,MAAM,WAAW,sBAAsB;IACrC,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;IACnB,iDAAiD;IACjD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAED,wEAAwE;AACxE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC,CA2B3H;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,GAAG,sBAAsB,EAAE,CASlG;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,iBAAiB,EACpE,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,QAAQ,EAAE,SAAS,sBAAsB,EAAE,GAC1C,CAAC,EAAE,CAmBL;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,GAAG,MAAM,GAAG,IAAI,CAOhG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,SAAS,sBAAsB,EAAE,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAQlI;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,EAAE,CAEnG;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,kCAAkC;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAAG,mBAAmB,EAAE,CAK3G;AAED;;;;;;;;;GASG;AACH,wBAAgB,gCAAgC,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAM3G"}