feat: Add beta mode support to Message builder

Add support for the beta attribute on the <messageML> tag, as introduced
in messageml-utils PR #421. This enables experimental features like
<sym-ai-context> for Symphony AI integration.

Changes:
- Add beta field to Message class and MessageBuilder
- When beta=true, wrap content with <messageML beta="true">
- Throw MessageCreationException if beta=true but content is already
  wrapped without the beta attribute
- Add unit tests for all beta mode scenarios

Author: thibauult

symphony-bdk-core/src/main/java/com/symphony/bdk/core/service/message/model/Message.java

@@ -58,6 +58,12 @@ public class Message {
    * @since Agent 20.14
    */
   private final Boolean silent;
+  /**
+   * Optional boolean flag to enable beta features in MessageML.
+   * When set to true, the messageML wrapper will include the beta="true" attribute,
+   * enabling experimental features like sym-ai-context.
+   */
+  private final Boolean beta;
 
   Message(final MessageBuilder builder) {
     this.content = builder.content();
@@ -66,6 +72,7 @@ public class Message {
     this.attachments = builder.attachments();
     this.previews = builder.previews();
     this.silent = builder.silent();
+    this.beta = builder.beta();
   }
 
   /**
@@ -94,6 +101,7 @@ public static class MessageBuilder {
     private String content;
     private String data;
     private Boolean silent = Boolean.TRUE;
+    private Boolean beta;
     private List<Attachment> attachments = new ArrayList<>();
     @Setter(value = AccessLevel.PRIVATE) private List<Attachment> previews = new ArrayList<>();
 
@@ -149,6 +157,19 @@ public MessageBuilder silent(@Nonnull Boolean silent) {
       return this;
     }
 
+    /**
+     * Enable beta mode for the message.
+     * When set to true, the messageML wrapper will include the beta="true" attribute,
+     * enabling experimental features like sym-ai-context.
+     *
+     * @param beta true to enable beta features, false or null to disable.
+     * @return this builder with beta configured.
+     */
+    public MessageBuilder beta(Boolean beta) {
+      this.beta = beta;
+      return this;
+    }
+
     /**
      * Add attachment to the message.
      * @param content Attachment content.
@@ -185,9 +206,19 @@ public Message build() {
       }
 
       // check if content is encapsulated in <messageML/> node
-      if (!this.content.startsWith("<messageML>") && !this.content.endsWith("</messageML>")) {
+      boolean isAlreadyWrapped = this.content.startsWith("<messageML") && this.content.endsWith("</messageML>");
+      if (!isAlreadyWrapped) {
         log.trace("Processing content to prefix with <messageML> and suffix with </messageML>");
-        this.content = "<messageML>" + this.content + "</messageML>";
+        if (Boolean.TRUE.equals(this.beta)) {
+          this.content = "<messageML beta=\"true\">" + this.content + "</messageML>";
+        } else {
+          this.content = "<messageML>" + this.content + "</messageML>";
+        }
+      } else if (Boolean.TRUE.equals(this.beta) && this.content.startsWith("<messageML>")) {
+        // beta=true but content is already wrapped without beta attribute
+        throw new MessageCreationException(
+            "Cannot set beta=true when content is already wrapped with <messageML> without the beta attribute. "
+            + "Either remove the wrapper or include beta=\"true\" in your messageML tag.");
       }
 
       // check done below because it will rejected by the agent otherwise

symphony-bdk-core/src/test/java/com/symphony/bdk/core/service/message/model/MessageTest.java

@@ -1,7 +1,9 @@
 package com.symphony.bdk.core.service.message.model;
 
 import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 
 import com.symphony.bdk.core.service.message.exception.MessageCreationException;
 
@@ -38,4 +40,43 @@ void checkMessageSilentValueIfSet() {
   void checkMessageSilentDefaultValue() {
     assertEquals(Boolean.TRUE, Message.builder().content("<messageML>hello</messageML>").build().getSilent());
   }
+
+  @Test
+  void checkBetaModeNotAddedByDefault() {
+    Message message = Message.builder().content("hello").build();
+    assertEquals("<messageML>hello</messageML>", message.getContent());
+    assertNull(message.getBeta());
+  }
+
+  @Test
+  void checkBetaModeAddedWhenTrue() {
+    Message message = Message.builder().content("hello").beta(true).build();
+    assertEquals("<messageML beta=\"true\">hello</messageML>", message.getContent());
+    assertEquals(Boolean.TRUE, message.getBeta());
+  }
+
+  @Test
+  void checkBetaModeNotAddedWhenFalse() {
+    Message message = Message.builder().content("hello").beta(false).build();
+    assertEquals("<messageML>hello</messageML>", message.getContent());
+    assertEquals(Boolean.FALSE, message.getBeta());
+  }
+
+  @Test
+  void checkBetaTrueWithPreWrappedContentThrowsException() {
+    MessageCreationException exception = assertThrows(
+        MessageCreationException.class,
+        () -> Message.builder().content("<messageML>hello</messageML>").beta(true).build()
+    );
+    assertTrue(exception.getMessage().contains("Cannot set beta=true when content is already wrapped"));
+  }
+
+  @Test
+  void checkBetaTrueWithPreWrappedBetaContentAllowed() {
+    Message message = Message.builder()
+        .content("<messageML beta=\"true\">hello</messageML>")
+        .beta(true)
+        .build();
+    assertEquals("<messageML beta=\"true\">hello</messageML>", message.getContent());
+  }
 }