src/core/message.js

/**

 * Message System - Typed conversation data structures

 *

 * Implementation similar to LangChain.js message system

 *

 * @module src/core/message.js

 */

/**

 * BaseMessage - Foundation for all message types

 *

 * Contains common functionality:

 * - Content storage

 * - Metadata tracking

 * - Timestamps

 * - Serialization

 */
export class BaseMessage {
  constructor(content, additionalKwargs = {}) {
    this.content = content;
    this.additionalKwargs = additionalKwargs;
    this.timestamp = Date.now();
    this.id = this.generateId();
  }

  /**

   * Generate unique ID for this message

   */
  generateId() {
    return `msg_${this.timestamp}_${Math.random().toString(36).substr(2, 9)}`;
  }

  /**

   * Get the message type (overridden in subclasses)

   */
  get type() {
    throw new Error('Subclass must implement type getter');
  }

  /**

   * Convert to JSON for storage/transmission

   */
  toJSON() {
    return {
      id: this.id,
      type: this.type,
      content: this.content,
      timestamp: this.timestamp,
      ...this.additionalKwargs
    };
  }

  /**

   * Create message from JSON

   */
  static fromJSON(json) {
    const MessageClass = MESSAGE_TYPES[json.type];
    if (!MessageClass) {
      throw new Error(`Unknown message type: ${json.type}`);
    }

    const message = new MessageClass(json.content, json.additionalKwargs);
    message.id = json.id;
    message.timestamp = json.timestamp;
    return message;
  }

  /**

   * Format for display

   */
  toString() {
    const date = new Date(this.timestamp).toLocaleTimeString();
    return `[${date}] ${this.type}: ${this.content}`;
  }
}

/**

 * SystemMessage - Instructions for the AI

 *

 * Sets the context, role, and constraints for the assistant.

 * Typically appears at the start of conversations.

 */
export class SystemMessage extends BaseMessage {
  constructor(content, additionalKwargs = {}) {
    super(content, additionalKwargs);
  }

  get type() {
    return 'system';
  }

  /**

   * System messages often need special formatting

   */
  toPromptFormat() {
    return {
      role: 'system',
      content: this.content
    };
  }
}

/**

 * HumanMessage - User input

 *

 * Represents messages from the human/user.

 * The primary input the AI responds to.

 */
export class HumanMessage extends BaseMessage {
  constructor(content, additionalKwargs = {}) {
    super(content, additionalKwargs);
  }

  get type() {
    return 'human';
  }

  toPromptFormat() {
    return {
      role: 'user',
      content: this.content
    };
  }
}

/**

 * AIMessage - Assistant responses

 *

 * Represents messages from the AI assistant.

 * Can include tool calls for function execution.

 */
export class AIMessage extends BaseMessage {
  constructor(content, additionalKwargs = {}) {
    super(content, additionalKwargs);

    // Tool calls are requests to execute functions
    this.toolCalls = additionalKwargs.toolCalls || [];
  }

  get type() {
    return 'ai';
  }

  /**

   * Check if this message requests tool execution

   */
  hasToolCalls() {
    return this.toolCalls.length > 0;
  }

  /**

   * Get specific tool call by index

   */
  getToolCall(index = 0) {
    return this.toolCalls[index];
  }

  toPromptFormat() {
    const formatted = {
      role: 'assistant',
      content: this.content
    };

    if (this.hasToolCalls()) {
      formatted.tool_calls = this.toolCalls;
    }

    return formatted;
  }
}

/**

 * ToolMessage - Tool execution results

 *

 * Contains the output from executing a tool/function.

 * Sent back to the AI to inform its next response.

 */
export class ToolMessage extends BaseMessage {
  constructor(content, toolCallId, additionalKwargs = {}) {
    super(content, additionalKwargs);
    this.toolCallId = toolCallId;
  }

  get type() {
    return 'tool';
  }

  toPromptFormat() {
    return {
      role: 'tool',
      content: this.content,
      tool_call_id: this.toolCallId
    };
  }
}

/**

 * Registry mapping type strings to message classes

 */
export const MESSAGE_TYPES = {
  'system': SystemMessage,
  'human': HumanMessage,
  'ai': AIMessage,
  'tool': ToolMessage
};

/**

 * Helper function to convert messages to prompt format

 *

 * @param {Array<BaseMessage>} messages - Array of messages

 * @returns {Array<Object>} Messages in LLM format

 */
export function messagesToPromptFormat(messages) {
  return messages.map(msg => msg.toPromptFormat());
}

/**

 * Helper function to filter messages by type

 *

 * @param {Array<BaseMessage>} messages - Array of messages

 * @param {string} type - Message type to filter

 * @returns {Array<BaseMessage>} Filtered messages

 */
export function filterMessagesByType(messages, type) {
  return messages.filter(msg => msg._type === type);
}

/**

 * Helper function to get the last N messages

 *

 * @param {Array<BaseMessage>} messages - Array of messages

 * @param {number} n - Number of messages to get

 * @returns {Array<BaseMessage>} Last N messages

 */
export function getLastMessages(messages, n) {
  return messages.slice(-n);
}

/**

 * Helper to merge consecutive messages of the same type

 * Useful for reducing token count

 *

 * @param {Array<BaseMessage>} messages - Array of messages

 * @returns {Array<BaseMessage>} Merged messages

 */
export function mergeConsecutiveMessages(messages) {
  if (messages.length === 0) return [];

  const merged = [messages[0]];

  for (let i = 1; i < messages.length; i++) {
    const current = messages[i];
    const last = merged[merged.length - 1];

    // Merge if same type and both are strings
    if (
        current._type === last._type &&
        typeof current.content === 'string' &&
        typeof last.content === 'string' &&
        current._type !== 'tool' // Don't merge tool messages
    ) {
      // Create new merged message
      const MessageClass = MESSAGE_CLASSES[current._type];
      const mergedContent = last.content + '\n' + current.content;
      merged[merged.length - 1] = new MessageClass(mergedContent, {
        name: last.name,
        additionalKwargs: { ...last.additionalKwargs, merged: true }
      });
    } else {
      merged.push(current);
    }
  }

  return merged;
}

export default {
  BaseMessage,
  SystemMessage,
  HumanMessage,
  AIMessage,
  ToolMessage,
  MESSAGE_TYPES
};