@acorex-platform/module-conversation-client 0.0.37 → 0.0.46

package/fesm2022/acorex-platform-module-conversation-client-contracts.mjs

@@ -1,8 +1,12 @@
+import { isLocaleStringMap, resolveMultiLanguageString } from '@acorex-platform/framework-shared/core';
+
 //#region ---- Comment entity reference ----
 //#endregion
 
 const AXPConversationMenuKeys = {
     Conversations: 'Conversation:Menu:Conversations',
+    Channels: 'Conversation:Menu:Channels',
+    Feed: 'Conversation:Menu:ChannelFeed',
 };
 
 /**
@@ -17,8 +21,34 @@ const AXPCollaborationPermissionKeys = {
     MaintainCommunications: 'Collaboration:Permission:MaintainCommunications',
     MaintainReservations: 'Collaboration:Permission:MaintainReservations',
     MaintainHelpDesk: 'Collaboration:Permission:MaintainHelpDesk',
+    ViewBulletins: 'Collaboration:Permission:ViewBulletins',
+    MaintainBulletins: 'Collaboration:Permission:MaintainBulletins',
+    PublishBulletins: 'Collaboration:Permission:PublishBulletins',
+    ModerateBulletinDiscussions: 'Collaboration:Permission:ModerateBulletinDiscussions',
     Setup: 'Collaboration:Permission:Setup',
 };
+const viewBulletins = AXPCollaborationPermissionKeys.ViewBulletins;
+const maintainBulletins = AXPCollaborationPermissionKeys.MaintainBulletins;
+const publishBulletins = AXPCollaborationPermissionKeys.PublishBulletins;
+function channelPostCrud() {
+    return {
+        Management: maintainBulletins,
+        View: viewBulletins,
+        Edit: maintainBulletins,
+        Delete: maintainBulletins,
+        Create: maintainBulletins,
+        Publish: publishBulletins,
+    };
+}
+function channelChildCrud() {
+    return {
+        Management: maintainBulletins,
+        View: viewBulletins,
+        Edit: maintainBulletins,
+        Delete: maintainBulletins,
+        Create: maintainBulletins,
+    };
+}
 /**
  * @deprecated Prefer {@link AXPCollaborationPermissionKeys}.
  * Legacy nested shape kept so existing imports compile during migration.
@@ -26,6 +56,9 @@ const AXPCollaborationPermissionKeys = {
 const AXMPermissionsKeys = {
     Conversation: {
         Management: AXPCollaborationPermissionKeys.MaintainConversations,
+        ChannelPosts: channelPostCrud(),
+        ChannelAudiences: channelChildCrud(),
+        ChannelReceipts: channelChildCrud(),
     },
 };
 
@@ -55,8 +88,270 @@ const RootConfig = {
             source: `${config.module}.Message`,
             icon: 'fa-light fa-message',
         },
+        channelPost: {
+            name: 'ChannelPost',
+            source: `${config.module}.ChannelPost`,
+            title: `@${config.i18n}:entities.channel-post.title`,
+            titlePlural: `@${config.i18n}:entities.channel-post.plural`,
+            icon: 'fa-light fa-bullhorn',
+        },
+        channelAudience: {
+            name: 'ChannelAudience',
+            source: `${config.module}.ChannelAudience`,
+            title: `@${config.i18n}:entities.channel-audience.title`,
+            titlePlural: `@${config.i18n}:entities.channel-audience.plural`,
+            icon: 'fa-light fa-users',
+        },
+        channelReceipt: {
+            name: 'ChannelReceipt',
+            source: `${config.module}.ChannelReceipt`,
+            title: `@${config.i18n}:entities.channel-receipt.title`,
+            titlePlural: `@${config.i18n}:entities.channel-receipt.plural`,
+            icon: 'fa-light fa-envelope-open',
+        },
+    },
+    pages: {
+        feed: {
+            path: 'announcements',
+            title: `@${config.i18n}:pages.feed.title`,
+            description: `@${config.i18n}:pages.feed.description`,
+            icon: 'fa-light fa-bullhorn',
+        },
+    },
+};
+const CHANNEL_POST_ENTITY_NAME = RootConfig.entities.channelPost.source;
+const CHANNEL_AUDIENCE_ENTITY_NAME = RootConfig.entities.channelAudience.source;
+const CHANNEL_RECEIPT_ENTITY_NAME = RootConfig.entities.channelReceipt.source;
+
+//#region ----   Imports   ----
+//#endregion
+//#region ----   Manifest Definition   ----
+/**
+ * Conversation Module Manifest.
+ * Defines module metadata, features, and provider references.
+ */
+const ConversationManifest = {
+    name: RootConfig.module.name,
+    version: '1.0.0',
+    title: RootConfig.module.title,
+    icon: RootConfig.module.icon,
+    i18n: RootConfig.config.i18n,
+    type: 'domain',
+    domain: 'communication',
+    // Module dependencies
+    dependencies: ['CommunicationManagement'],
+};
+//#endregion
+
+const AXMChannelErrorCodes = {
+    InvalidTransition: 'CHANNEL_INVALID_TRANSITION',
+    ScheduleRequiresFuturePublishAt: 'CHANNEL_SCHEDULE_REQUIRES_FUTURE_PUBLISH_AT',
+    NotAddressed: 'CHANNEL_NOT_ADDRESSED',
+};
+
+//#region ----- Conversation channel runtime keys -----
+const AXPConversationQueryKeys = {
+    ChannelFeed: {
+        Get: 'Conversation:ChannelFeed:Get',
+        GetUnreadCount: 'Conversation:ChannelFeed:GetUnreadCount',
     },
 };
+const AXPConversationCommandKeys = {
+    ChannelFeed: {
+        MarkRead: 'Conversation:ChannelFeed:MarkRead',
+    },
+};
+//#endregion
+
+//#region ----- Imports -----
+//#endregion
+
+//#region ----- Imports -----
+//#endregion
+//#region ----- Mapping -----
+/** Projects a channel post onto the chat/feed card shape stored on Message metadata. */
+function toChannelFeedItem(post, isRead, isPinned, commentCount = 0) {
+    return {
+        id: post.id,
+        roomId: post.roomId,
+        title: post.title,
+        body: post.body,
+        kind: post.kind,
+        authorUserId: post.authorUserId,
+        publishedAt: toIso(post.publishedAt),
+        eventStartsAt: toIso(post.eventStartsAt),
+        eventEndsAt: toIso(post.eventEndsAt),
+        eventLocation: post.eventLocation,
+        isPinned,
+        allowReactions: post.allowReactions,
+        allowComments: post.allowComments,
+        commentCount,
+        isRead,
+        gallery: asFileList(post.gallery),
+        attachments: asFileList(post.attachments),
+        tags: asTags(post.tags),
+    };
+}
+/** Plain-text title for chat message payload (MLS or string). */
+function channelPostTitleText(title) {
+    if (typeof title === 'string') {
+        return title;
+    }
+    if (title == null) {
+        return '';
+    }
+    try {
+        return JSON.stringify(title);
+    }
+    catch {
+        return '';
+    }
+}
+function channelPostMessageName(postId) {
+    return `channel-post:${postId}`;
+}
+//#endregion
+//#region ----- Helpers -----
+function toIso(value) {
+    if (!value) {
+        return undefined;
+    }
+    const date = value instanceof Date ? value : new Date(value);
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+}
+function asTags(value) {
+    if (value == null) {
+        return [];
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed) {
+            return [];
+        }
+        try {
+            return asTags(JSON.parse(trimmed));
+        }
+        catch {
+            return [trimmed];
+        }
+    }
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((item) => normalizeTag(item))
+        .filter((item) => item != null);
+}
+function normalizeTag(value) {
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        return trimmed.length > 0 ? trimmed : null;
+    }
+    if (isLocaleStringMap(value)) {
+        const hasContent = Object.values(value).some((entry) => typeof entry === 'string' && entry.trim().length > 0);
+        return hasContent ? value : null;
+    }
+    return null;
+}
+function asFileList(value) {
+    if (value == null) {
+        return [];
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        if (!trimmed) {
+            return [];
+        }
+        try {
+            return asFileList(JSON.parse(trimmed));
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.filter((item) => item != null && typeof item === 'object' && typeof item.name === 'string');
+}
+//#endregion
+
+//#region ----- Imports -----
+//#endregion
+//#region ----- Distribution & notification contracts -----
+const CHANNEL_POST_PUBLISHED_EVENT_NAME = 'Conversation.ChannelPostPublished';
+const CHANNEL_DISTRIBUTOR = Symbol('CHANNEL_DISTRIBUTOR');
+const CHANNEL_NOTIFICATION_PORT = Symbol('CHANNEL_NOTIFICATION_PORT');
+//#endregion
+
+//#region ----- Imports -----
+//#endregion
+//#region ----- Constants -----
+const TARGET_MEMBERSHIP_KEY = {
+    user: 'userId',
+    role: 'roleIds',
+    team: 'teamIds',
+    businessUnit: 'businessUnitIds',
+    position: 'positionIds',
+    jobDefinition: 'jobDefinitionIds',
+};
+//#endregion
+//#region ----- Audience matching -----
+function axmChannelAudienceRuleMatches(rule, member) {
+    if (rule.targetType === 'organization') {
+        return true;
+    }
+    const key = TARGET_MEMBERSHIP_KEY[rule.targetType];
+    const value = member[key];
+    return Array.isArray(value) ? value.includes(rule.targetId ?? '') : value === rule.targetId;
+}
+function axmChannelAudienceIsVisible(rules, member) {
+    if (rules.length === 0) {
+        return true;
+    }
+    const included = rules.some((rule) => rule.mode !== 'exclude' && axmChannelAudienceRuleMatches(rule, member));
+    const excluded = rules.some((rule) => rule.mode === 'exclude' && axmChannelAudienceRuleMatches(rule, member));
+    return included && !excluded;
+}
+function axmResolveChannelAudienceUserIds(rules, members) {
+    return members.filter((member) => axmChannelAudienceIsVisible(rules, member)).map((member) => member.userId);
+}
+//#endregion
+
+//#region ----- Imports -----
+//#endregion
+//#region ----- Target entity map -----
+/** Lookup entity for each audience target type. `organization` has no row lookup. */
+const AXM_CHANNEL_AUDIENCE_TARGET_ENTITY = {
+    organization: null,
+    user: 'SecurityManagement.User',
+    role: 'SecurityManagement.Role',
+    team: 'OrganizationManagement.Team',
+    businessUnit: 'OrganizationManagement.BusinessUnit',
+    position: 'OrganizationManagement.Position',
+    jobDefinition: 'OrganizationManagement.JobDefinition',
+};
+function axmChannelAudienceTargetEntity(targetType) {
+    if (!targetType) {
+        return null;
+    }
+    return AXM_CHANNEL_AUDIENCE_TARGET_ENTITY[targetType] ?? null;
+}
+function axmRoomAudienceRule(room) {
+    const roomId = room.id?.trim();
+    const targetType = room.audienceTargetType?.trim();
+    if (!roomId || !targetType) {
+        return null;
+    }
+    return {
+        id: `room-audience:${roomId}`,
+        roomId,
+        targetType,
+        targetId: room.audienceTargetId?.trim() || undefined,
+        mode: room.audienceMode?.trim() ?? 'include',
+    };
+}
+//#endregion
 
 //#region ---- Media helpers ----
 //#endregion
@@ -74,10 +369,136 @@ const AXM_COMMENT_LIKE_EMOJI = '👍';
 //#region ---- Imports ----
 //#endregion
 
+//#region ----- Imports -----
+//#endregion
+
+//#region ----- Imports -----
+//#endregion
+
+//#region ----- Imports -----
+//#endregion
+
+//#region ----- Constants -----
+/** Persisted `Room.name` for the tenant-wide announcements channel (unique per tenant scope). */
+const AXM_CONVERSATION_ANNOUNCEMENT_CHANNEL_NAME = 'system.tenant-announcements';
+/** `metadata.systemChannel` value for the tenant-wide announcements channel. */
+const AXM_CONVERSATION_ANNOUNCEMENT_CHANNEL_KEY = 'announcements';
+/** Custom conversation message type rendered by the channel feed-item plugin. */
+const AXM_CONVERSATION_ANNOUNCEMENT_MESSAGE_TYPE = 'channel-feed-item';
+/** Message metadata key that stores the `AXMChannelFeedItem` projection. */
+const AXM_CONVERSATION_ANNOUNCEMENT_FEED_ITEM_META_KEY = 'channelFeedItem';
+/** Message metadata key that stores the source ChannelPost id. */
+const AXM_CONVERSATION_CHANNEL_POST_ID_META_KEY = 'channelPostId';
+/** True when the room is the tenant announcements channel. */
+function axmIsAnnouncementChannel(value) {
+    if (!value) {
+        return false;
+    }
+    if (value.name === AXM_CONVERSATION_ANNOUNCEMENT_CHANNEL_NAME) {
+        return true;
+    }
+    return value.metadata?.['systemChannel'] === AXM_CONVERSATION_ANNOUNCEMENT_CHANNEL_KEY;
+}
+function axmAnnouncementChannelMetadata() {
+    return {
+        systemChannel: AXM_CONVERSATION_ANNOUNCEMENT_CHANNEL_KEY,
+        reactionsEnabled: false,
+    };
+}
+/** True when the room is an entity comment thread (not a chat inbox conversation). */
+function axmIsCommentRoom(value) {
+    return value?.kind === 'comment';
+}
+/** True when the room is a chat channel (broadcast posts, no composer). */
+function axmIsChannelRoom(value) {
+    if (!value) {
+        return false;
+    }
+    if (axmIsAnnouncementChannel(value)) {
+        return true;
+    }
+    return value.type === 'channel';
+}
+function axmChannelPostIdFromMessage(message) {
+    if (!message) {
+        return null;
+    }
+    const meta = message.metadata ?? {};
+    const fromMeta = meta[AXM_CONVERSATION_CHANNEL_POST_ID_META_KEY];
+    if (typeof fromMeta === 'string' && fromMeta.trim()) {
+        return fromMeta.trim();
+    }
+    const prefix = 'channel-post:';
+    const name = message.name?.trim() ?? '';
+    if (name.startsWith(prefix)) {
+        const id = name.slice(prefix.length).trim();
+        if (id) {
+            return id;
+        }
+    }
+    const feed = meta[AXM_CONVERSATION_ANNOUNCEMENT_FEED_ITEM_META_KEY];
+    if (feed && typeof feed === 'object' && typeof feed.id === 'string') {
+        const id = feed.id.trim();
+        return id || null;
+    }
+    return null;
+}
+//#endregion
+
+//#region ---- Conversation message scope ----
+/**
+ * Resolves tenant/application scope for a new {@link Conversation.Message} row.
+ * Prefer the parent room's stamped scope so call logs match sibling messages on read.
+ */
+function axmResolveConversationMessageScopeInfo(room, session) {
+    const fromRoom = readScopeInfo(room['scopeInfo']);
+    if (fromRoom?.['tenantId']) {
+        return fromRoom;
+    }
+    const tenantId = session.tenantId?.trim();
+    if (!tenantId) {
+        return undefined;
+    }
+    const scope = { tenantId };
+    const applicationId = session.applicationId?.trim();
+    if (applicationId) {
+        scope['applicationId'] = applicationId;
+    }
+    return scope;
+}
+function axmScopeInfoNeedsTenantStamp(scopeInfo, expectedTenantId) {
+    const tenantId = typeof scopeInfo?.['tenantId'] === 'string' ? scopeInfo['tenantId'].trim() : '';
+    return tenantId !== expectedTenantId.trim();
+}
+function readScopeInfo(value) {
+    if (!value || typeof value !== 'object') {
+        return undefined;
+    }
+    const record = value;
+    const tenantId = typeof record['tenantId'] === 'string' ? record['tenantId'].trim() : '';
+    if (!tenantId) {
+        return undefined;
+    }
+    const scope = { tenantId };
+    const applicationId = typeof record['applicationId'] === 'string' ? record['applicationId'].trim() : '';
+    if (applicationId) {
+        scope['applicationId'] = applicationId;
+    }
+    return scope;
+}
+//#endregion
+
 //#region ---- Assist stream wire events (shared with server) ----
 //#endregion
 
 //#region ---- Assist metadata helpers (shared) ----
+/** UI flags persisted on every AI (bot) room. */
+function axmAiChatConversationUiMetadata() {
+    return {
+        reactionsEnabled: false,
+        composerAttachmentPresentation: 'banner',
+    };
+}
 function axmExtractAssistIdFromMetadata(metadata) {
     if (!metadata) {
         return undefined;
@@ -155,16 +576,29 @@ function axmReadAssistResponseStatus(metadata) {
     const status = metadata?.['assistResponseStatus'];
     return typeof status === 'string' ? status : undefined;
 }
+function axmReadAssistFollowUpStatus(metadata) {
+    const status = metadata?.['followUpStatus'];
+    if (status === 'preparing' || status === 'ready' || status === 'skipped') {
+        return status;
+    }
+    return undefined;
+}
 function axmReadReplyToUserMessageId(metadata) {
     const replyTo = metadata?.['replyToUserMessageId'];
     return typeof replyTo === 'string' && replyTo.trim() ? replyTo.trim() : undefined;
 }
 function extractMessageTextFromPayload(payload) {
+    if (!payload || typeof payload !== 'object') {
+        return '';
+    }
     const record = payload;
-    if (record?.type === 'text' && typeof record.text === 'string') {
-        return record.text;
+    if (typeof record.text !== 'string') {
+        return '';
     }
-    return '';
+    if (record.type && record.type !== 'text') {
+        return '';
+    }
+    return record.text;
 }
 function axmNormalizeConversationTitle(raw) {
     const normalized = raw
@@ -174,6 +608,50 @@ function axmNormalizeConversationTitle(raw) {
         .trim();
     return normalized.slice(0, 90).trim();
 }
+/** System prompt for a lightweight follow-up-chip model call after the Assist answer. */
+const AXM_ASSIST_CONVERSATION_FOLLOW_UP_SYSTEM_PROMPT = `You generate short follow-up suggestion chips for a chat assistant.
+
+Given the latest user message, assistant reply, optional this-turn tool evidence, optional earlier turns from **this same conversation**, and optional assist capabilities, reply with ONLY one JSON object:
+{"type":"followUp","content":[{"text":"chip label","command":{"name":"Conversation:SendAssistChatMessage","options":{}}}]}
+
+Rules:
+- Always propose 2–5 short, actionable next steps as Conversation:SendAssistChatMessage chips. Never return an empty content array.
+- Navigation chips (Entity:OpenList / Entity:OpenDetails) are extra and never replace send-message chips. Always include at least two send-message chips.
+- Default chips send the label as the next chat message via Conversation:SendAssistChatMessage.
+- **Priority:** ground every chip in the latest user message and the latest assistant reply. Earlier turns in this conversation may only inspire wording. Ignore any other conversation, tenant, or leftover memory.
+- Chip labels must continue **this exchange**. After a list or query (including an empty result), suggest the next obvious question or filter — a different date, range, person, or related view — in the user's language. After a create/update, offer the next step on that record.
+- Empty results still need concrete next steps (for example a different day, this week, or who is away), not generic filler.
+- Example: user asked who is on leave today and the assistant found none → chips such as "leave tomorrow", "this week's leave", "who is away next week" in the user's language.
+- Never emit generic filler such as "Ask another question", "What else can you do?", "Ask me anything", or their translations.
+- Navigation chips only when **this turn** created, updated, queried, opened a specific entity, or answered a how-to using PlatformManagement:ListPlatformNavigationForAi with a single Module.Entity. Never on greeting, thanks, goodbye, or orientation. Chip **text** must be in the same language as the user (never English when the user wrote Persian).
+  - List: {"text":"<Open List or List {menu title} in the user's language>","command":{"name":"Entity:OpenList","options":{"entity":"Module.Entity"}}}
+  - How-to / menu answers: Open List only (no Details unless a record id exists). Prefer a named chip such as "List Users" when the menu title is known.
+  - Details (only when this turn has a record id and the row was not just deleted): {"text":"<Open Details in the user's language>","command":{"name":"Entity:OpenDetails","options":{"entity":"Module.Entity","data":{"id":"<record-id>"}}}}
+- Other chips remain send-message requests in the user's language.
+- Do not invent platform facts, IDs, or screens that were not mentioned and are not listed in assist capabilities.
+- When the exchange is orientation (greeting, thanks, goodbye, or no specific task yet), suggest what this assist can help with. Prefer the provided assist capabilities, rewritten as short chip labels in the user's language.
+- Use the same language as the user.
+- Do not repeat the assistant's full answer. Chip labels only.
+- No markdown fences, commentary, or extra keys.`;
+function axmBuildAssistConversationFollowUpUserPrompt(input) {
+    const parts = [
+        `Latest user message (authoritative):\n${input.userMessageText.trim()}`,
+        `Latest assistant reply (authoritative):\n${input.assistantMessageText.trim()}`,
+    ];
+    const turn = input.turnGrounding?.trim();
+    if (turn) {
+        parts.push(turn);
+    }
+    const thread = input.threadInspiration?.trim();
+    if (thread) {
+        parts.push(`Earlier turns in this conversation only (optional inspiration; do not override the latest exchange; ignore any other chat):\n${thread}`);
+    }
+    const grounding = input.assistGrounding?.trim();
+    if (grounding) {
+        parts.push(grounding);
+    }
+    return parts.join('\n\n');
+}
 /** System prompt for a lightweight title-only model call (first user message → sidebar title). */
 const AXM_ASSIST_CONVERSATION_TITLE_SYSTEM_PROMPT = `You generate short conversation titles for chat sidebars.
 
@@ -242,17 +720,381 @@ function axmCompareMessagesChronologically(a, b) {
     const diff = axmCoerceMessageTimestampMs(a.timestamp) - axmCoerceMessageTimestampMs(b.timestamp);
     return diff !== 0 ? diff : a.id.localeCompare(b.id);
 }
+/** Messages that sort after {@link messageId} in conversation order (deleted rows excluded). */
+function axmMessagesAfterId(messages, messageId) {
+    const scoped = messageId.trim();
+    if (!scoped) {
+        return [];
+    }
+    const sorted = [...messages].sort((a, b) => axmCompareMessagesChronologically(a, b));
+    const idx = sorted.findIndex((message) => message.id === scoped);
+    if (idx < 0) {
+        return [];
+    }
+    return sorted.slice(idx + 1).filter((message) => message.deleted !== true);
+}
+//#endregion
+
+//#region ---- Follow-up nav chip locale ----
+/** Must match `conversation.json` → `chat.assist-renderer.follow-up.open-entity-list`. */
+const AXM_FOLLOW_UP_OPEN_LIST_LABELS = {
+    'en-US': 'Open List',
+    'en-AU': 'Open List',
+    'fa-IR': 'باز کردن لیست',
+};
+/** Must match `conversation.json` → `chat.assist-renderer.follow-up.open-entity-list-named`. */
+const AXM_FOLLOW_UP_OPEN_LIST_NAMED_LABELS = {
+    'en-US': 'List {{name}}',
+    'en-AU': 'List {{name}}',
+    'fa-IR': 'لیست {{name}}',
+};
+/** Must match `conversation.json` → `chat.assist-renderer.follow-up.open-entity-details`. */
+const AXM_FOLLOW_UP_OPEN_DETAILS_LABELS = {
+    'en-US': 'Open Details',
+    'en-AU': 'Open Details',
+    'fa-IR': 'باز کردن جزئیات',
+};
+const FOLLOW_UP_CHIP_LOCALES = ['en-US', 'en-AU', 'fa-IR'];
+const PERSIAN_OR_ARABIC_SCRIPT = /[\u0600-\u06FF]/;
+function normalizeChipLocale(raw) {
+    const locale = raw?.trim() || 'en-US';
+    return locale;
+}
+function isKnownChipLocale(locale) {
+    return FOLLOW_UP_CHIP_LOCALES.includes(locale);
+}
+/**
+ * Spoken language from the latest user text when that locale exists in the product;
+ * otherwise the system UI locale.
+ */
+function axmInferFollowUpChipLocale(spokenText, systemLocale) {
+    const system = normalizeChipLocale(systemLocale);
+    const text = spokenText.trim();
+    let spoken;
+    if (PERSIAN_OR_ARABIC_SCRIPT.test(text)) {
+        spoken = 'fa-IR';
+    }
+    else if (/[A-Za-z]/.test(text)) {
+        spoken = system.toLowerCase().startsWith('en') ? system : 'en-US';
+    }
+    if (spoken && isKnownChipLocale(spoken)) {
+        return spoken;
+    }
+    if (isKnownChipLocale(system)) {
+        return system;
+    }
+    return 'en-US';
+}
+/** Resolved Open List / Open Details labels — plain text, never i18n keys. */
+function axmResolveFollowUpNavChipLabels(spokenText, systemLocale, options) {
+    const locale = axmInferFollowUpChipLocale(spokenText, systemLocale);
+    const namedTitle = options?.listEntityTitle?.trim();
+    const listTemplate = namedTitle
+        ? resolveMultiLanguageString(AXM_FOLLOW_UP_OPEN_LIST_NAMED_LABELS, locale)
+        : resolveMultiLanguageString(AXM_FOLLOW_UP_OPEN_LIST_LABELS, locale);
+    return {
+        list: namedTitle ? listTemplate.replace(/\{\{\s*name\s*\}\}/g, namedTitle) : listTemplate,
+        details: resolveMultiLanguageString(AXM_FOLLOW_UP_OPEN_DETAILS_LABELS, locale),
+    };
+}
 //#endregion
 
 //#region ---- Assist message handler port (server) ----
 const AXM_CONVERSATION_ASSIST_MESSAGE_HANDLER = Symbol('AXM_CONVERSATION_ASSIST_MESSAGE_HANDLER');
 //#endregion
 
+//#region ----- Types -----
+/** Metadata key on a Conversation room for contextual assist launch payload. */
+const AXM_ASSIST_LAUNCH_CONTEXT_METADATA_KEY = 'assistLaunchContext';
+/** v1 entity-row launch kind. Later callers may pass other kind strings (e.g. document). */
+const AXM_CONTEXTUAL_ASSIST_KIND_ENTITY_RECORD = 'entity-record';
+/** v1 entity-row action name passed into the launcher. */
+const AXM_CONTEXTUAL_ASSIST_ACTION_ENTITY_RECORD = 'entity.record.assist';
+/**
+ * Payload key for a live designer/document JSON string.
+ * Sanitizer keeps this field much larger than ordinary string values.
+ */
+const AXM_CONTEXTUAL_ASSIST_LAYOUT_JSON_KEY = 'layoutJson';
+//#endregion
+
+//#region ----- Imports -----
+//#endregion
+//#region ----- Constants -----
+const STARTER_MAX_CHIPS = 3;
+const MAX_STRING_CHARS = 400;
+const MAX_JSON_CHARS = 800;
+/** Live designer JSON must survive sanitize so the specialist can edit the canvas. */
+const AXM_CONTEXTUAL_ASSIST_MAX_LAYOUT_JSON_CHARS = 100_000;
+const LARGE_CONTEXT_STRING_KEYS = new Set([
+    AXM_CONTEXTUAL_ASSIST_LAYOUT_JSON_KEY,
+    'documentJson',
+    'formJson',
+]);
+const SECRET_NAME_PATTERN = /password|secret|token|apikey|api_key|credential|privatekey|private_key/i;
+const AXM_CONTEXTUAL_ASSIST_STARTER_SYSTEM_PROMPT = `You generate short suggested starter questions for a chat assistant.
+
+The user has not sent a message yet. They opened assist from a product surface (for example one entity record).
+
+Reply with ONLY one JSON object:
+{"items":[{"text":"short question"}]}
+
+Rules:
+- Return at most 3 items. Each text is one short suggested question or request the user could send.
+- Ground every chip only in the provided launch context. Do not invent ids, fields, or facts that are not in the context.
+- Use the same language as the locale (and any user-facing titles in the context).
+- Do not claim data was saved or that you already changed the record.
+- No markdown fences, commentary, or extra keys.`;
+//#endregion
+//#region ----- Metadata -----
+/**
+ * Reads {@link AXM_ASSIST_LAUNCH_CONTEXT_METADATA_KEY} from conversation metadata
+ * (including the nested `metadata.metadata` shape used by the conversation UI).
+ */
+function axmIsFormTemplateDesignerAssistLaunch(metadata) {
+    const ctx = axmExtractAssistLaunchContextFromMetadata(metadata);
+    if (!ctx) {
+        return false;
+    }
+    return ctx.kind === 'form-template-designer' || ctx.payload['scenario'] === 'form-template-designer';
+}
+function axmExtractAssistLaunchContextFromMetadata(metadata) {
+    if (!metadata) {
+        return undefined;
+    }
+    const direct = readLaunchContext(metadata[AXM_ASSIST_LAUNCH_CONTEXT_METADATA_KEY]);
+    if (direct) {
+        return direct;
+    }
+    const nested = metadata['metadata'];
+    if (nested && typeof nested === 'object' && !Array.isArray(nested)) {
+        return readLaunchContext(nested[AXM_ASSIST_LAUNCH_CONTEXT_METADATA_KEY]);
+    }
+    return undefined;
+}
+function readLaunchContext(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return undefined;
+    }
+    const row = raw;
+    const kind = typeof row['kind'] === 'string' ? row['kind'].trim() : '';
+    const actionName = typeof row['actionName'] === 'string' ? row['actionName'].trim() : '';
+    const payload = row['payload'];
+    if (!kind || !actionName || !payload || typeof payload !== 'object' || Array.isArray(payload)) {
+        return undefined;
+    }
+    const title = typeof row['title'] === 'string' ? row['title'].trim() : undefined;
+    return {
+        kind,
+        actionName,
+        ...(title ? { title } : {}),
+        payload: payload,
+    };
+}
+//#endregion
+//#region ----- Sanitize -----
+function axmSanitizeContextualAssistContext(context) {
+    const title = context.title?.trim();
+    return {
+        kind: context.kind.trim(),
+        actionName: context.actionName.trim(),
+        ...(title ? { title } : {}),
+        payload: sanitizeRecord(context.payload, 0),
+    };
+}
+function sanitizeRecord(value, depth) {
+    const out = {};
+    for (const [key, raw] of Object.entries(value)) {
+        if (shouldSkipKey(key)) {
+            continue;
+        }
+        const next = sanitizeUnknown(raw, depth + 1, key);
+        if (next !== undefined) {
+            out[key] = next;
+        }
+    }
+    return out;
+}
+function axmSanitizeContextualAssistValue(value) {
+    return sanitizeUnknown(value, 0);
+}
+function sanitizeUnknown(value, depth, key) {
+    if (value == null) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        const trimmed = value.trim();
+        const maxChars = key && LARGE_CONTEXT_STRING_KEYS.has(key) ? AXM_CONTEXTUAL_ASSIST_MAX_LAYOUT_JSON_CHARS : MAX_STRING_CHARS;
+        return trimmed.length > maxChars ? `${trimmed.slice(0, maxChars)}…` : trimmed;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return value;
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === 'function' || typeof value === 'bigint' || typeof value === 'symbol') {
+        return undefined;
+    }
+    if (Array.isArray(value)) {
+        if (depth > 2) {
+            return summarizeJson(value);
+        }
+        return value
+            .slice(0, 12)
+            .map((item) => sanitizeUnknown(item, depth + 1))
+            .filter((item) => item !== undefined);
+    }
+    if (typeof value === 'object') {
+        if (depth > 2) {
+            return summarizeJson(value);
+        }
+        return sanitizeRecord(value, depth);
+    }
+    return undefined;
+}
+function axmShouldSkipContextualAssistKey(key) {
+    return shouldSkipKey(key);
+}
+function shouldSkipKey(key) {
+    const trimmed = key.trim();
+    if (!trimmed || trimmed.startsWith('_') || trimmed.startsWith('$')) {
+        return true;
+    }
+    return SECRET_NAME_PATTERN.test(trimmed);
+}
+function summarizeJson(value) {
+    try {
+        const text = JSON.stringify(value);
+        if (!text || text === '{}' || text === '[]') {
+            return undefined;
+        }
+        return text.length > MAX_JSON_CHARS ? `${text.slice(0, MAX_JSON_CHARS)}…` : text;
+    }
+    catch {
+        return undefined;
+    }
+}
+//#endregion
+//#region ----- Prompts -----
+function axmBuildContextualAssistStarterUserPrompt(context, locale) {
+    const sanitized = axmSanitizeContextualAssistContext(context);
+    const localeLabel = locale.trim() || 'en-US';
+    return [
+        `Locale: ${localeLabel}`,
+        `Action: ${sanitized.actionName}`,
+        `Kind: ${sanitized.kind}`,
+        sanitized.title ? `Surface title: ${sanitized.title}` : '',
+        'Launch context (JSON):',
+        JSON.stringify(sanitized.payload, null, 2),
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+/** System/user-visible injection prepended on every assist run for a launched room. */
+function axmFormatContextualAssistLaunchInjection(context) {
+    const sanitized = axmSanitizeContextualAssistContext(context);
+    return [
+        'The user opened assist from a product surface. Use this launch context for the whole conversation.',
+        'Do not invent persisted ids or claim data was saved.',
+        `Action: ${sanitized.actionName}`,
+        `Kind: ${sanitized.kind}`,
+        sanitized.title ? `Surface title: ${sanitized.title}` : '',
+        sanitized.kind === 'form-template-designer' ||
+            sanitized.payload['scenario'] === 'form-template-designer' ||
+            typeof sanitized.payload[AXM_CONTEXTUAL_ASSIST_LAYOUT_JSON_KEY] === 'string'
+            ? [
+                'The Form Template designer canvas is open.',
+                'Follow the edit-layout-designer Skill: Page:GetContext then Page:RunAction with add-widget / update-widget / remove-widget / move-widget from snapshot.actions.',
+                'Calculated fields, show/hide, and cascades use write-platform-expression: patch node.triggers and node.visible (not options.hint).',
+                'Read snapshot.outline for widget name/type/path. Do not rewrite or apply the full layout JSON for a single field. Do not emit a widget tree in chat.',
+                'The user-visible chat reply is one or two short sentences only.',
+            ].join(' ')
+            : '',
+        'Context (JSON):',
+        JSON.stringify(sanitized.payload, null, 2),
+    ]
+        .filter(Boolean)
+        .join('\n');
+}
+//#endregion
+//#region ----- Parse starters -----
+function axmParseContextualAssistStarterItems(rawText) {
+    const parsed = parseJsonPayload(rawText);
+    const labels = [];
+    for (const candidate of collectStarterCandidates(parsed)) {
+        const text = candidate.trim();
+        if (!text) {
+            continue;
+        }
+        labels.push(text);
+        if (labels.length >= STARTER_MAX_CHIPS) {
+            break;
+        }
+    }
+    return labels;
+}
+function collectStarterCandidates(parsed) {
+    if (Array.isArray(parsed)) {
+        return parsed.map(labelFromUnknown).filter(Boolean);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        return [];
+    }
+    const row = parsed;
+    const items = row['items'] ?? row['content'];
+    if (!Array.isArray(items)) {
+        return [];
+    }
+    return items.map(labelFromUnknown).filter(Boolean);
+}
+function labelFromUnknown(value) {
+    if (typeof value === 'string') {
+        return value.trim();
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const text = value['text'];
+        if (typeof text === 'string') {
+            return text.trim();
+        }
+    }
+    return '';
+}
+function parseJsonPayload(rawText) {
+    let text = rawText.trim();
+    if (!text) {
+        return null;
+    }
+    text = text.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/u, '').trim();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        const objectStart = text.indexOf('{');
+        const arrayStart = text.indexOf('[');
+        const startCandidates = [objectStart, arrayStart].filter((index) => index >= 0);
+        if (startCandidates.length === 0) {
+            return null;
+        }
+        const start = Math.min(...startCandidates);
+        const end = text.lastIndexOf(start === objectStart ? '}' : ']');
+        if (end <= start) {
+            return null;
+        }
+        try {
+            return JSON.parse(text.slice(start, end + 1));
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//#endregion
+
 //#region ---- Contracts barrel ----
 
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { AXMPermissionsKeys, AXM_ASSIST_CONVERSATION_TITLE_SYSTEM_PROMPT, AXM_COMMENT_LIKE_EMOJI, AXM_CONVERSATION_ASSIST_MESSAGE_HANDLER, AXPCollaborationPermissionKeys, AXPConversationMenuKeys, RootConfig, axmBuildHeuristicConversationTitleFallback, axmChatAiPeerParticipantId, axmCoerceMessageTimestampMs, axmCompareMessagesChronologically, axmConversationHasAiChat, axmEnsureAssistMessageSortsAfterReplyTarget, axmExtractAssistIdFromMetadata, axmExtractDirectAgentIdFromMetadata, axmIsUnsupportedLegacyAgentAssistConversation, axmNormalizeConversationTitle, axmReadAssistResponseStatus, axmReadReplyToUserMessageId, axmResolveAssistMessageTimestamp, axmSanitizeAiGeneratedConversationTitle, extractMessageTextFromPayload };
+export { AXMChannelErrorCodes, AXMPermissionsKeys, AXM_ASSIST_CONVERSATION_FOLLOW_UP_SYSTEM_PROMPT, AXM_ASSIST_CONVERSATION_TITLE_SYSTEM_PROMPT, AXM_ASSIST_LAUNCH_CONTEXT_METADATA_KEY, AXM_CHANNEL_AUDIENCE_TARGET_ENTITY, AXM_COMMENT_LIKE_EMOJI, AXM_CONTEXTUAL_ASSIST_ACTION_ENTITY_RECORD, AXM_CONTEXTUAL_ASSIST_KIND_ENTITY_RECORD, AXM_CONTEXTUAL_ASSIST_LAYOUT_JSON_KEY, AXM_CONTEXTUAL_ASSIST_MAX_LAYOUT_JSON_CHARS, AXM_CONTEXTUAL_ASSIST_STARTER_SYSTEM_PROMPT, AXM_CONVERSATION_ANNOUNCEMENT_CHANNEL_KEY, AXM_CONVERSATION_ANNOUNCEMENT_CHANNEL_NAME, AXM_CONVERSATION_ANNOUNCEMENT_FEED_ITEM_META_KEY, AXM_CONVERSATION_ANNOUNCEMENT_MESSAGE_TYPE, AXM_CONVERSATION_ASSIST_MESSAGE_HANDLER, AXM_CONVERSATION_CHANNEL_POST_ID_META_KEY, AXPCollaborationPermissionKeys, AXPConversationCommandKeys, AXPConversationMenuKeys, AXPConversationQueryKeys, CHANNEL_AUDIENCE_ENTITY_NAME, CHANNEL_DISTRIBUTOR, CHANNEL_NOTIFICATION_PORT, CHANNEL_POST_ENTITY_NAME, CHANNEL_POST_PUBLISHED_EVENT_NAME, CHANNEL_RECEIPT_ENTITY_NAME, ConversationManifest, RootConfig, axmAiChatConversationUiMetadata, axmAnnouncementChannelMetadata, axmBuildAssistConversationFollowUpUserPrompt, axmBuildContextualAssistStarterUserPrompt, axmBuildHeuristicConversationTitleFallback, axmChannelAudienceIsVisible, axmChannelAudienceRuleMatches, axmChannelAudienceTargetEntity, axmChannelPostIdFromMessage, axmChatAiPeerParticipantId, axmCoerceMessageTimestampMs, axmCompareMessagesChronologically, axmConversationHasAiChat, axmEnsureAssistMessageSortsAfterReplyTarget, axmExtractAssistIdFromMetadata, axmExtractAssistLaunchContextFromMetadata, axmExtractDirectAgentIdFromMetadata, axmFormatContextualAssistLaunchInjection, axmInferFollowUpChipLocale, axmIsAnnouncementChannel, axmIsChannelRoom, axmIsCommentRoom, axmIsFormTemplateDesignerAssistLaunch, axmIsUnsupportedLegacyAgentAssistConversation, axmMessagesAfterId, axmNormalizeConversationTitle, axmParseContextualAssistStarterItems, axmReadAssistFollowUpStatus, axmReadAssistResponseStatus, axmReadReplyToUserMessageId, axmResolveAssistMessageTimestamp, axmResolveChannelAudienceUserIds, axmResolveConversationMessageScopeInfo, axmResolveFollowUpNavChipLabels, axmRoomAudienceRule, axmSanitizeAiGeneratedConversationTitle, axmSanitizeContextualAssistContext, axmSanitizeContextualAssistValue, axmScopeInfoNeedsTenantStamp, axmShouldSkipContextualAssistKey, channelPostMessageName, channelPostTitleText, extractMessageTextFromPayload, toChannelFeedItem };
 //# sourceMappingURL=acorex-platform-module-conversation-client-contracts.mjs.map