Class ConversationUtility

Utility class for parsing and formatting special content in conversation messages Handles @{...} syntax for mentions, forms, and other structured content

All content uses the @{...} wrapper with a _mode field to distinguish types. If _mode is omitted, defaults to "mention" for backward compatibility.

Example: Parsing message content

const tokens = ConversationUtility.ParseSpecialContent(message);
const plainText = ConversationUtility.ToPlainText(message, agents, users);
const agentContext = ConversationUtility.ToAgentContext(message, agents, users);
const html = ConversationUtility.ToHTML(message, agents, users);

Constructors

constructor

new ConversationUtility(): ConversationUtility
Returns ConversationUtility

Properties

`Static` `Readonly`RECORD_LINK_RESERVED_KEYS

RECORD_LINK_RESERVED_KEYS: readonly [
    "_mode",
    "type",
    "name",
    "entityName",
    "configurationId",
    "configurationName",
    "configId",
    "config",
    "keys",
    "id",
] = ...

Field names on a mention token that are never primary-key values. Composite PK fields that collide with these go under keys instead.

Methods

`Static`BuildChatMessageContent

BuildChatMessageContent(
    messageText: string,
    attachmentData: AttachmentData[],
    agents?: AgentInfo[],
    users?: UserInfo[],
): Promise<ChatMessageContent>
Build ChatMessageContent from text and attachment data. This is the primary method for converting stored messages to AI-ready format.
Parameters
- messageText: string
  The message text (may contain @{...} tokens)
- attachmentData: AttachmentData[]
  Array of attachment data with content
- Optionalagents: AgentInfo[]
  Optional agents for mention resolution
- Optionalusers: UserInfo[]
  Optional users for mention resolution
Returns Promise<ChatMessageContent>
ChatMessageContent ready for AI provider
- Defined in AI/CorePlus/src/conversation-utility.ts:437

`Static`CompositeKeyFromOpenResource

CompositeKeyFromOpenResource(
command: { keys?: Record<string, string | number>; resourceId?: string },
primaryKeyNames: string[],
): CompositeKey
Build a CompositeKey from an open:resource Record command. keys wins per field; resourceId fills a single PK (or a PK named ID).
Parameters
- command: { keys?: Record<string, string | number>; resourceId?: string }
- primaryKeyNames: string[]
Returns CompositeKey
- Defined in AI/CorePlus/src/conversation-utility.ts:364

`Static`CompositeKeyFromRecordLink

CompositeKeyFromRecordLink(
content: MentionContent,
primaryKeyNames: string[],
): CompositeKey
Build a CompositeKey from a record-link token using the entity's PK field names (from EntityInfo.PrimaryKeys). Returns null if any PK part is missing.
Parameters
- content: MentionContent
- primaryKeyNames: string[]
Returns CompositeKey
- Defined in AI/CorePlus/src/conversation-utility.ts:341

`Static`ContainsAttachments

ContainsAttachments(text: string): boolean
Check if a message contains attachment references
Parameters
- text: string
  The message text to check
Returns boolean
true if the message contains attachment syntax
- Defined in AI/CorePlus/src/conversation-utility.ts:407

`Static`ContainsFormResponse

ContainsFormResponse(text: string): boolean
Check if a message contains form response syntax (@{"_mode":"form",...}) Useful for fast-path routing decisions without running full LLM inference.

Form responses should always be routed back to the agent that requested the form, so this can be used to skip intent-checking prompts entirely.
Parameters
- text: string
  The message text to check
Returns boolean
true if the message contains form response syntax
- Defined in AI/CorePlus/src/conversation-utility.ts:222

`Static`CreateAttachmentReference

CreateAttachmentReference(attachment: AttachmentContent): string
Create an attachment reference token string
Parameters
- attachment: AttachmentContent
  The attachment content object
Returns string
Formatted @{...} string for the attachment reference
- Defined in AI/CorePlus/src/conversation-utility.ts:393

`Static`CreateFormResponse

CreateFormResponse(
    action: string,
    fields: { label?: string; name: string; value: any }[],
    title?: string,
): string
Create a form response token string
Parameters
- action: string
  The action being performed (e.g., "createRecord")
- fields: { label?: string; name: string; value: any }[]
  Array of field name/value pairs
- Optionaltitle: string
  Optional form title for display
Returns string
Formatted @{...} string for the form response
- Defined in AI/CorePlus/src/conversation-utility.ts:197

`Static`CreateMention

CreateMention(
    type: "user" | "entity" | "agent" | "query",
    id: string,
    name: string,
    configurationId?: string,
    configurationName?: string,
): string
Create a mention token string
Parameters
- type: "user" | "entity" | "agent" | "query"
  Type of mention (agent, user, entity, or query)
- id: string
  ID of the mentioned entity
- name: string
  Name of the mentioned entity
- OptionalconfigurationId: string
  Optional agent configuration ID
- OptionalconfigurationName: string
  Optional agent configuration name
Returns string
Formatted @{...} string for the mention
- Defined in AI/CorePlus/src/conversation-utility.ts:238

`Static`CreateRecordLink

CreateRecordLink(
    entityName: string,
    name: string,
    primaryKey: Record<string, string | number>,
): string
Create a clickable record-link token for Chat message. Primary-key fields are siblings named as in entity metadata. Reserved names land in nested keys.

name is the pill label. Omit it (or pass empty) for an icon-only pill — the right call when surrounding prose already names the record.
Parameters
- entityName: string
- name: string
- primaryKey: Record<string, string | number>
Returns string
- Defined in AI/CorePlus/src/conversation-utility.ts:282

`Static`GetAttachmentReferences

GetAttachmentReferences(text: string): AttachmentContent[]
Get all attachment references from a message
Parameters
- text: string
  The message text to parse
Returns AttachmentContent[]
Array of attachment content objects
- Defined in AI/CorePlus/src/conversation-utility.ts:419

`Static`GetAttachmentTypeFromMime

GetAttachmentTypeFromMime(mimeType: string): AttachmentType
Determine the attachment type from a MIME type
Parameters
- mimeType: string
  The MIME type of the file
Returns AttachmentType
The attachment type category
- Defined in AI/CorePlus/src/conversation-utility.ts:601

`Static`GetContentBlockType

GetContentBlockType(
attachmentType: AttachmentType,
): "image_url" | "video_url" | "audio_url" | "file_url"
Get the ChatMessageContentBlock type from attachment type
Parameters
- attachmentType: AttachmentType
  The attachment type
Returns "image_url" | "video_url" | "audio_url" | "file_url"
The corresponding content block type
- Defined in AI/CorePlus/src/conversation-utility.ts:617

`Static`GetEffectiveLimit

GetEffectiveLimit(
    limitName: keyof AttachmentLimits,
    agentLimits: Partial<AttachmentLimits>,
    modelLimits: Partial<AttachmentLimits>,
    systemDefaults: AttachmentDefaults,
): number
Get the effective limit value using cascade: agent → model → system
Parameters
- limitName: keyof AttachmentLimits
  The name of the limit to get
- agentLimits: Partial<AttachmentLimits>
  Agent-level overrides
- modelLimits: Partial<AttachmentLimits>
  Model-level limits
- systemDefaults: AttachmentDefaults
  System defaults
Returns number
The effective limit value
- Defined in AI/CorePlus/src/conversation-utility.ts:558

`Static`ParseSpecialContent

ParseSpecialContent(text: string): SpecialContentToken[]
Parse all @{...} tokens in a message Returns array of parsed content with their positions
Parameters
- text: string
  The message text to parse
Returns SpecialContentToken[]
Array of parsed tokens with positions and content
- Defined in AI/CorePlus/src/conversation-utility.ts:50

`Static`RecordLinkKeyMap

RecordLinkKeyMap(content: MentionContent): Record<string, string | number>
All PK-ish values on a record-link token: nested keys, sibling fields, and id as an alias for ID.
Parameters
- content: MentionContent
Returns Record<string, string | number>
- Defined in AI/CorePlus/src/conversation-utility.ts:314

`Static`ShouldStoreInline

ShouldStoreInline(
    sizeBytes: number,
    agentThreshold: number,
    systemThreshold: number,
): boolean
Determine if an attachment should be stored inline or in MJStorage
Parameters
- sizeBytes: number
  Size of the attachment in bytes
- agentThreshold: number
  Agent-level threshold override (optional)
- systemThreshold: number
  System default threshold
Returns boolean
true if should be stored inline, false if should use MJStorage
- Defined in AI/CorePlus/src/conversation-utility.ts:586

`Static`ToAgentContext

ToAgentContext(text: string, agents?: AgentInfo[], users?: UserInfo[]): string
Convert message for agent consumption (LLM input)
- Mentions: Just the name "Agent Name" (no @ prefix)
- Forms: Full JSON for agent to understand context
Parameters
- text: string
  The message text to convert
- Optionalagents: AgentInfo[]
  Optional array of agent information for name lookup
- Optionalusers: UserInfo[]
  Optional array of user information for name lookup
Returns string
Agent-friendly representation of the message
- Defined in AI/CorePlus/src/conversation-utility.ts:153

`Static`ToPlainText

ToPlainText(text: string, agents?: AgentInfo[], users?: UserInfo[]): string
Convert message to plain text (for display/export)
- Mentions: "@Agent Name" or "@User Name"
- Forms: "Form Response: Field1=Value1, Field2=Value2"
Parameters
- text: string
  The message text to convert
- Optionalagents: AgentInfo[]
  Optional array of agent information for name lookup
- Optionalusers: UserInfo[]
  Optional array of user information for name lookup
Returns string
Plain text representation of the message
- Defined in AI/CorePlus/src/conversation-utility.ts:113

`Static`ValidateAttachment

ValidateAttachment(
    attachment: { sizeBytes: number; type: AttachmentType },
    currentCounts: {
        audios: number;
        documents: number;
        images: number;
        videos: number;
    },
    agentLimits: Partial<AttachmentLimits>,
    modelLimits: Partial<AttachmentLimits>,
    systemDefaults: AttachmentDefaults,
): AttachmentValidationResult
Validate an attachment against size and count limits. Uses the cascade: agent → model → system defaults
Parameters
- attachment: { sizeBytes: number; type: AttachmentType }
  The attachment to validate
- currentCounts: { audios: number; documents: number; images: number; videos: number }
  Current counts of attachments in the message
- agentLimits: Partial<AttachmentLimits>
  Agent-level limit overrides (optional)
- modelLimits: Partial<AttachmentLimits>
  Model-level limits (optional)
- systemDefaults: AttachmentDefaults
  System default limits
Returns AttachmentValidationResult
Validation result with allowed flag and optional reason
- Defined in AI/CorePlus/src/conversation-utility.ts:487

Class ConversationUtility

Example: Parsing message content

Index

Constructors

Properties

Methods

Constructors

constructor

Returns ConversationUtility

Properties

Static ReadonlyRECORD_LINK_RESERVED_KEYS

Methods

StaticBuildChatMessageContent

Parameters

Returns Promise<ChatMessageContent>

StaticCompositeKeyFromOpenResource

Parameters

Returns CompositeKey

StaticCompositeKeyFromRecordLink

Parameters

Returns CompositeKey

StaticContainsAttachments

Parameters

Returns boolean

StaticContainsFormResponse

Parameters

Returns boolean

StaticCreateAttachmentReference

Parameters

Returns string

StaticCreateFormResponse

Parameters

Returns string

StaticCreateMention

Parameters

Returns string

StaticCreateRecordLink

Parameters

Returns string

StaticGetAttachmentReferences

Parameters

Returns AttachmentContent[]

StaticGetAttachmentTypeFromMime

Parameters

Returns AttachmentType

StaticGetContentBlockType

Parameters

Returns "image_url" | "video_url" | "audio_url" | "file_url"

StaticGetEffectiveLimit

Parameters

Returns number

StaticParseSpecialContent

Parameters

Returns SpecialContentToken[]

StaticRecordLinkKeyMap

Parameters

Returns Record<string, string | number>

StaticShouldStoreInline

Parameters

Returns boolean

StaticToAgentContext

Parameters

Returns string

StaticToPlainText

Parameters

Returns string

StaticValidateAttachment

Parameters

Returns AttachmentValidationResult

Settings

On This Page

`Static` `Readonly`RECORD_LINK_RESERVED_KEYS

`Static`BuildChatMessageContent

`Static`CompositeKeyFromOpenResource

`Static`CompositeKeyFromRecordLink

`Static`ContainsAttachments

`Static`ContainsFormResponse

`Static`CreateAttachmentReference

`Static`CreateFormResponse

`Static`CreateMention

`Static`CreateRecordLink

`Static`GetAttachmentReferences

`Static`GetAttachmentTypeFromMime

`Static`GetContentBlockType

`Static`GetEffectiveLimit

`Static`ParseSpecialContent

`Static`RecordLinkKeyMap

`Static`ShouldStoreInline

`Static`ToAgentContext

`Static`ToPlainText

`Static`ValidateAttachment