Add messageId overloads to prompt context send methods

Add sendMessage(text, messageId) and sendThought(text, messageId) as default
methods on PromptContext and SyncPromptContext. They delegate to the existing
sendUpdate with the three-argument chunk constructor, so no implementation
changes are needed and external implementors are unaffected.

Lets agents group or identify streamed chunks via the per-chunk messageId
field without dropping to the low-level sendUpdate API.

Author: Mark Pollack

CHANGELOG.md

@@ -17,7 +17,9 @@ Protocol currency: catching up to ACP spec v0.13.6 (June 2026).
   stored session; gated on the `sessionCapabilities.delete` capability.
 - `additionalDirectories` on `session/new`, `session/load`, `session/resume`, `session/fork` requests
   and on `SessionInfo` — extra workspace roots beyond `cwd`.
-- Per-chunk `messageId` on `AgentMessageChunk`, `AgentThoughtChunk`, `UserMessageChunk`.
+- Per-chunk `messageId` on `AgentMessageChunk`, `AgentThoughtChunk`, `UserMessageChunk`, plus
+  `sendMessage(text, messageId)` / `sendThought(text, messageId)` convenience overloads on
+  `PromptContext` and `SyncPromptContext`.
 - `sessionCapabilities.delete` and `sessionCapabilities.additionalDirectories`, surfaced via
   `NegotiatedCapabilities` (`supports*`/`require*`).
 

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/PromptContext.java

@@ -188,6 +188,19 @@ public interface PromptContext {
 	 */
 	Mono<Void> sendMessage(String text);
 
+	/**
+	 * Sends a message to the client as an agent message chunk, tagged with a message ID.
+	 * Chunks sharing the same {@code messageId} belong to the same logical message; a change
+	 * in {@code messageId} signals a new message.
+	 * @param text The message text to send
+	 * @param messageId The message identifier, or {@code null} for none
+	 * @return A Mono that completes when the message is sent
+	 */
+	default Mono<Void> sendMessage(String text, String messageId) {
+		return sendUpdate(getSessionId(),
+				new AcpSchema.AgentMessageChunk("agent_message_chunk", new AcpSchema.TextContent(text), messageId));
+	}
+
 	/**
 	 * Sends a thought to the client as an agent thought chunk.
 	 * Thoughts are typically displayed differently than messages,
@@ -197,6 +210,18 @@ public interface PromptContext {
 	 */
 	Mono<Void> sendThought(String text);
 
+	/**
+	 * Sends a thought to the client as an agent thought chunk, tagged with a message ID.
+	 * Chunks sharing the same {@code messageId} belong to the same logical message.
+	 * @param text The thought text to send
+	 * @param messageId The message identifier, or {@code null} for none
+	 * @return A Mono that completes when the thought is sent
+	 */
+	default Mono<Void> sendThought(String text, String messageId) {
+		return sendUpdate(getSessionId(),
+				new AcpSchema.AgentThoughtChunk("agent_thought_chunk", new AcpSchema.TextContent(text), messageId));
+	}
+
 	/**
 	 * Reads a text file from the client's file system.
 	 * @param path The path to the file

acp-core/src/main/java/com/agentclientprotocol/sdk/agent/SyncPromptContext.java

@@ -184,6 +184,18 @@ public interface SyncPromptContext {
 	 */
 	void sendMessage(String text);
 
+	/**
+	 * Sends a message to the client as an agent message chunk, tagged with a message ID.
+	 * Chunks sharing the same {@code messageId} belong to the same logical message; a change
+	 * in {@code messageId} signals a new message.
+	 * @param text The message text to send
+	 * @param messageId The message identifier, or {@code null} for none
+	 */
+	default void sendMessage(String text, String messageId) {
+		sendUpdate(getSessionId(),
+				new AcpSchema.AgentMessageChunk("agent_message_chunk", new AcpSchema.TextContent(text), messageId));
+	}
+
 	/**
 	 * Sends a thought to the client as an agent thought chunk.
 	 * Thoughts are typically displayed differently than messages,
@@ -192,6 +204,17 @@ public interface SyncPromptContext {
 	 */
 	void sendThought(String text);
 
+	/**
+	 * Sends a thought to the client as an agent thought chunk, tagged with a message ID.
+	 * Chunks sharing the same {@code messageId} belong to the same logical message.
+	 * @param text The thought text to send
+	 * @param messageId The message identifier, or {@code null} for none
+	 */
+	default void sendThought(String text, String messageId) {
+		sendUpdate(getSessionId(),
+				new AcpSchema.AgentThoughtChunk("agent_thought_chunk", new AcpSchema.TextContent(text), messageId));
+	}
+
 	/**
 	 * Reads a text file from the client's file system.
 	 * @param path The path to the file

acp-core/src/test/java/com/agentclientprotocol/sdk/agent/ConvenienceApiTest.java

@@ -148,6 +148,48 @@ void sendMessageSendsAgentMessageChunk() throws Exception {
 		agent.closeGracefully();
 	}
 
+	@Test
+	void sendMessageWithMessageIdSetsMessageId() throws Exception {
+		List<SessionNotification> receivedUpdates = new CopyOnWriteArrayList<>();
+		CountDownLatch latch = new CountDownLatch(1);
+
+		AcpSyncAgent agent = AcpAgent.sync(transportPair.agentTransport())
+			.requestTimeout(TIMEOUT)
+			.initializeHandler(req -> InitializeResponse.ok())
+			.newSessionHandler(req -> new NewSessionResponse("msgid-session", null, null))
+			.promptHandler((request, context) -> {
+				context.sendMessage("Hello with id!", "msg-7");
+				return PromptResponse.endTurn();
+			})
+			.build();
+
+		AcpAsyncClient client = AcpClient.async(transportPair.clientTransport())
+			.requestTimeout(TIMEOUT)
+			.sessionUpdateConsumer(notification -> {
+				receivedUpdates.add(notification);
+				latch.countDown();
+				return Mono.empty();
+			})
+			.build();
+
+		agent.start();
+		Thread.sleep(100);
+
+		client.initialize(new InitializeRequest(1, new ClientCapabilities())).block(TIMEOUT);
+		client.newSession(new NewSessionRequest("/workspace", List.of())).block(TIMEOUT);
+		client.prompt(new PromptRequest("msgid-session", List.of(new TextContent("test")))).block(TIMEOUT);
+
+		assertThat(latch.await(5, TimeUnit.SECONDS)).isTrue();
+		assertThat(receivedUpdates).hasSize(1);
+		assertThat(receivedUpdates.get(0).update()).isInstanceOf(AgentMessageChunk.class);
+		AgentMessageChunk chunk = (AgentMessageChunk) receivedUpdates.get(0).update();
+		assertThat(((TextContent) chunk.content()).text()).isEqualTo("Hello with id!");
+		assertThat(chunk.messageId()).isEqualTo("msg-7");
+
+		client.closeGracefully().block(TIMEOUT);
+		agent.closeGracefully();
+	}
+
 	@Test
 	void sendThoughtSendsAgentThoughtChunk() throws Exception {
 		List<SessionNotification> receivedUpdates = new CopyOnWriteArrayList<>();