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);

Index

Constructors

constructor

Methods

BuildChatMessageContent ContainsAttachments ContainsFormResponse CreateAttachmentReference CreateFormResponse CreateMention GetAttachmentReferences GetAttachmentTypeFromMime GetContentBlockType GetEffectiveLimit ParseSpecialContent ShouldStoreInline ToAgentContext ToPlainText ValidateAttachment

Constructors

constructor

new ConversationUtility(): ConversationUtility
Returns ConversationUtility

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:308

`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:278

`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:221

`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:264

`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:196

`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:237

`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:290

`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:472

`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:488

`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:429

`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:49

`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:457

`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:152

`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:112

`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:358

Class ConversationUtility

Example: Parsing message content

Index

Constructors

Methods

Constructors

constructor

Returns ConversationUtility

Methods

StaticBuildChatMessageContent

Parameters

Returns Promise<ChatMessageContent>

StaticContainsAttachments

Parameters

Returns boolean

StaticContainsFormResponse

Parameters

Returns boolean

StaticCreateAttachmentReference

Parameters

Returns string

StaticCreateFormResponse

Parameters

Returns string

StaticCreateMention

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[]

StaticShouldStoreInline

Parameters

Returns boolean

StaticToAgentContext

Parameters

Returns string

StaticToPlainText

Parameters

Returns string

StaticValidateAttachment

Parameters

Returns AttachmentValidationResult

Settings

On This Page

`Static`BuildChatMessageContent

`Static`ContainsAttachments

`Static`ContainsFormResponse

`Static`CreateAttachmentReference

`Static`CreateFormResponse

`Static`CreateMention

`Static`GetAttachmentReferences

`Static`GetAttachmentTypeFromMime

`Static`GetContentBlockType

`Static`GetEffectiveLimit

`Static`ParseSpecialContent

`Static`ShouldStoreInline

`Static`ToAgentContext

`Static`ToPlainText

`Static`ValidateAttachment