feat(schema): Stabilize optional message IDs (#1372)

benbrandt · web-flow · commit 92e0061a3752 · 2026-06-05T14:07:32.000+02:00
diff --git a/Cargo.toml b/Cargo.toml
@@ -29,7 +29,6 @@ unstable = [
     "unstable_plan_operations",
     "unstable_session_fork",
     "unstable_end_turn_token_usage",
-    "unstable_message_id",
     "unstable_boolean_config",
 ]
 # Protocol v2 is intentionally NOT part of the `unstable` umbrella.
@@ -46,7 +45,6 @@ unstable_nes = []
 unstable_plan_operations = []
 unstable_session_fork = []
 unstable_end_turn_token_usage = []
-unstable_message_id = []
 unstable_boolean_config = []
 
 # Emit `tracing::warn!` events when `VecSkipError` drops a malformed list
diff --git a/docs/docs.json b/docs/docs.json
@@ -209,7 +209,7 @@
           },
           {
             "group": "Preview",
-            "pages": ["rfds/rust-sdk-v1", "rfds/message-id"]
+            "pages": ["rfds/rust-sdk-v1"]
           },
           {
             "group": "Completed",
@@ -218,6 +218,7 @@
               "rfds/session-config-options",
               "rfds/session-list",
               "rfds/session-usage",
+              "rfds/message-id",
               "rfds/session-delete",
               "rfds/session-info-update",
               "rfds/meta-propagation",
diff --git a/docs/protocol/v1/draft/schema.mdx b/docs/protocol/v1/draft/schema.mdx
@@ -3501,11 +3501,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/d
   A single item of content
 </ResponseField>
 <ResponseField name="messageId" type={<><span><a href="#messageid">MessageId</a></span><span> | null</span></>} >
-  **UNSTABLE**
-
-This capability is not part of the spec yet, and may be removed or changed at any point.
-
-A unique identifier for the message this chunk belongs to.
+  A unique identifier for the message this chunk belongs to.
 
 All chunks belonging to the same message share the same `messageId`.
 A change in `messageId` indicates a new message has started.
@@ -7143,11 +7139,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/d
   A single item of content
 </ResponseField>
 <ResponseField name="messageId" type={<><span><a href="#messageid">MessageId</a></span><span> | null</span></>} >
-  **UNSTABLE**
-
-This capability is not part of the spec yet, and may be removed or changed at any point.
-
-A unique identifier for the message this chunk belongs to.
+  A unique identifier for the message this chunk belongs to.
 
 All chunks belonging to the same message share the same `messageId`.
 A change in `messageId` indicates a new message has started.
@@ -7177,11 +7169,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/d
   A single item of content
 </ResponseField>
 <ResponseField name="messageId" type={<><span><a href="#messageid">MessageId</a></span><span> | null</span></>} >
-  **UNSTABLE**
-
-This capability is not part of the spec yet, and may be removed or changed at any point.
-
-A unique identifier for the message this chunk belongs to.
+  A unique identifier for the message this chunk belongs to.
 
 All chunks belonging to the same message share the same `messageId`.
 A change in `messageId` indicates a new message has started.
@@ -7211,11 +7199,7 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/d
   A single item of content
 </ResponseField>
 <ResponseField name="messageId" type={<><span><a href="#messageid">MessageId</a></span><span> | null</span></>} >
-  **UNSTABLE**
-
-This capability is not part of the spec yet, and may be removed or changed at any point.
-
-A unique identifier for the message this chunk belongs to.
+  A unique identifier for the message this chunk belongs to.
 
 All chunks belonging to the same message share the same `messageId`.
 A change in `messageId` indicates a new message has started.
diff --git a/docs/protocol/v1/prompt-turn.mdx b/docs/protocol/v1/prompt-turn.mdx
@@ -154,6 +154,7 @@ The Agent then reports text responses from the model:
     "sessionId": "sess_abc123def456",
     "update": {
       "sessionUpdate": "agent_message_chunk",
+      "messageId": "msg_agent_c42b9",
       "content": {
         "type": "text",
         "text": "I'll analyze your code for potential issues. Let me examine it..."
@@ -163,6 +164,10 @@ The Agent then reports text responses from the model:
 }
 ```
 
+#### Message IDs
+
+The Agent **MAY** include an opaque, unique `messageId` on message chunks. Chunks with the same `messageId` belong to the same message; a changed `messageId` indicates a new message.
+
 If the model requested tool calls, these are also reported immediately:
 
 ```json
diff --git a/docs/protocol/v1/schema.mdx b/docs/protocol/v1/schema.mdx
@@ -1907,6 +1907,13 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e
 <ResponseField name="content" type={<a href="#contentblock">ContentBlock</a>} required>
   A single item of content
 </ResponseField>
+<ResponseField name="messageId" type={<><span><a href="#messageid">MessageId</a></span><span> | null</span></>} >
+  A unique identifier for the message this chunk belongs to.
+
+All chunks belonging to the same message share the same `messageId`.
+A change in `messageId` indicates a new message has started.
+
+</ResponseField>
 
 ## <span class="font-mono">Cost</span>
 
@@ -2512,6 +2519,12 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e
   Human-readable name identifying this MCP server.
 </ResponseField>
 
+## <span class="font-mono">MessageId</span>
+
+Unique identifier for a message within a session.
+
+**Type:** `string`
+
 ## <span class="font-mono">PermissionOption</span>
 
 An option presented to the user when requesting permission.
@@ -3335,6 +3348,13 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e
 </ResponseField>
 <ResponseField name="content" type={<a href="#contentblock">ContentBlock</a>} required>
   A single item of content
+</ResponseField>
+<ResponseField name="messageId" type={<><span><a href="#messageid">MessageId</a></span><span> | null</span></>} >
+  A unique identifier for the message this chunk belongs to.
+
+All chunks belonging to the same message share the same `messageId`.
+A change in `messageId` indicates a new message has started.
+
 </ResponseField>
 <ResponseField name="sessionUpdate" type={"string"} required>
   The discriminator value. Must be `"user_message_chunk"`.
@@ -3358,6 +3378,13 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e
 </ResponseField>
 <ResponseField name="content" type={<a href="#contentblock">ContentBlock</a>} required>
   A single item of content
+</ResponseField>
+<ResponseField name="messageId" type={<><span><a href="#messageid">MessageId</a></span><span> | null</span></>} >
+  A unique identifier for the message this chunk belongs to.
+
+All chunks belonging to the same message share the same `messageId`.
+A change in `messageId` indicates a new message has started.
+
 </ResponseField>
 <ResponseField name="sessionUpdate" type={"string"} required>
   The discriminator value. Must be `"agent_message_chunk"`.
@@ -3381,6 +3408,13 @@ See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v1/e
 </ResponseField>
 <ResponseField name="content" type={<a href="#contentblock">ContentBlock</a>} required>
   A single item of content
+</ResponseField>
+<ResponseField name="messageId" type={<><span><a href="#messageid">MessageId</a></span><span> | null</span></>} >
+  A unique identifier for the message this chunk belongs to.
+
+All chunks belonging to the same message share the same `messageId`.
+A change in `messageId` indicates a new message has started.
+
 </ResponseField>
 <ResponseField name="sessionUpdate" type={"string"} required>
   The discriminator value. Must be `"agent_thought_chunk"`.
diff --git a/docs/protocol/v1/session-setup.mdx b/docs/protocol/v1/session-setup.mdx
@@ -143,6 +143,7 @@ For example, a user message from the conversation history:
     "sessionId": "sess_789xyz",
     "update": {
       "sessionUpdate": "user_message_chunk",
+      "messageId": "msg_user_8f7a1",
       "content": {
         "type": "text",
         "text": "What's the capital of France?"
@@ -162,6 +163,7 @@ Followed by the agent's response:
     "sessionId": "sess_789xyz",
     "update": {
       "sessionUpdate": "agent_message_chunk",
+      "messageId": "msg_agent_c42b9",
       "content": {
         "type": "text",
         "text": "The capital of France is Paris."
@@ -171,6 +173,8 @@ Followed by the agent's response:
 }
 ```
 
+If the Agent provides message IDs during replay, each `messageId` is an opaque, unique identifier for the replayed message.
+
 When **all** the conversation entries have been streamed to the Client, the Agent **MUST** respond to the original `session/load` request.
 
 ```json
diff --git a/docs/protocol/v2/prompt-turn.mdx b/docs/protocol/v2/prompt-turn.mdx
@@ -158,6 +158,7 @@ The Agent then reports text responses from the model:
     "sessionId": "sess_abc123def456",
     "update": {
       "sessionUpdate": "agent_message_chunk",
+      "messageId": "msg_agent_c42b9",
       "content": {
         "type": "text",
         "text": "I'll analyze your code for potential issues. Let me examine it..."
@@ -167,6 +168,10 @@ The Agent then reports text responses from the model:
 }
 ```
 
+#### Message IDs
+
+The Agent **MUST** include an opaque `messageId` on message chunks. Chunks with the same `messageId` belong to the same message; a changed `messageId` indicates a new message.
+
 If the model requested tool calls, these are also reported immediately:
 
 ```json
diff --git a/docs/protocol/v2/session-setup.mdx b/docs/protocol/v2/session-setup.mdx
@@ -147,6 +147,7 @@ For example, a user message from the conversation history:
     "sessionId": "sess_789xyz",
     "update": {
       "sessionUpdate": "user_message_chunk",
+      "messageId": "msg_user_8f7a1",
       "content": {
         "type": "text",
         "text": "What's the capital of France?"
@@ -166,6 +167,7 @@ Followed by the agent's response:
     "sessionId": "sess_789xyz",
     "update": {
       "sessionUpdate": "agent_message_chunk",
+      "messageId": "msg_agent_c42b9",
       "content": {
         "type": "text",
         "text": "The capital of France is Paris."
@@ -175,6 +177,8 @@ Followed by the agent's response:
 }
 ```
 
+During replay, the Agent **MUST** include an opaque, unique `messageId` for each replayed message.
+
 When **all** the conversation entries have been streamed to the Client, the Agent **MUST** respond to the original `session/load` request.
 
 ```json
diff --git a/docs/rfds/message-id.mdx b/docs/rfds/message-id.mdx
@@ -70,7 +70,7 @@ Add a `messageId` field to `AgentMessageChunk`, `UserMessageChunk`, and `AgentTh
 
 ### Proposed Structure
 
-The `session/prompt` response does not include a message ID. In v1, there won't be a message ID for user-submitted messages. In v2, the agent will replay the message and attach the appropriate message ID to the user message.
+The `session/prompt` request and response do not include a message ID. Clients do not create protocol message IDs. If the Agent emits the accepted user message through `session/update`, it generates and attaches the appropriate message ID to that user message.
 
 If the Agent sends `user_message_chunk` updates (e.g., during `session/load`), it uses the user message ID:
 
@@ -282,6 +282,7 @@ Future RFDs may propose extending `messageId` to other update types if use cases
 
 ## Revision history
 
+- **2026-06-05**: Moved to Completed and stabilized optional v1 `messageId` in the stable protocol artifacts
 - **2026-06-03**: Moved the v1 portion of the RFD to Preview while v2-specific behavior remains part of the v2 draft work
 - **2026-06-03**: Moved the RFD out of the v2 Draft group while keeping v2-specific behavior; added a dedicated `MessageId` type, and made v2 require message IDs on streamed message chunks while v1 keeps optional message IDs for compatibility
 - **2026-06-02**: Updated the proposal so message IDs are Agent-generated only, removed client-provided prompt IDs and prompt response acknowledgments, and removed the UUID requirement in favor of opaque strings
diff --git a/docs/rfds/updates.mdx b/docs/rfds/updates.mdx
@@ -6,6 +6,13 @@ rss: true
 
 This page tracks lifecycle changes for ACP Requests for Dialog. For broader ACP announcements, see [Updates](/updates).
 
+<Update label="June 5, 2026" tags={["Completed"]}>
+## Message ID RFD moves to Completed
+
+The RFD for adding agent-generated `messageId` fields to streamed message chunks has been stabilized and is now part of the protocol. In v1, message IDs are optional on message chunks for compatibility; in v2, they are required. Please review the [documentation](/protocol/v1/prompt-turn#message-ids) for more information.
+
+</Update>
+
 <Update label="June 5, 2026" tags={["Completed"]}>
 ## Session Context Size and Cost RFD moves to Completed
 
diff --git a/docs/rfds/v2/prompt.mdx b/docs/rfds/v2/prompt.mdx
@@ -44,7 +44,7 @@ The agent will respond once the prompt has been _accepted_, not when the turn is
 }
 ```
 
-Given there will need to be some more exploration for Message IDs in general, I won't tie that RFD to this one unnecessarily. The accepted user message notification becomes the natural point to provide the required v2 message ID.
+The completed Message ID RFD keeps message IDs agent-owned. The accepted user message notification becomes the natural point to provide the required v2 message ID.
 
 Queueing messages (still an ongoing discussion) would also fit much nicer in this pattern. Either by adding additional parameters or a separate method, we can allow a client to submit queued messages and either cancel or edit them before they get accepted without having to mess with the turn semantics of the previous prompt request approach. Again, queueing is decidedly not part of this RFD, but it seems to fall more naturally into this semantic change in the prompt request.
 
@@ -64,7 +64,7 @@ The question then turns to what makes up this notification. Which brings us to:
 
 **Who owns the user message id?**
 
-The [message id RFD](/rfds/message-id) proposes that the agent owns message IDs. This means the client cannot eagerly create a protocol message ID for a prompt, but it also means we avoid a shared uniqueness or UUID requirement between clients and agents.
+The [message id RFD](/rfds/message-id) defines that the agent owns message IDs. This means the client cannot eagerly create a protocol message ID for a prompt, but it also means we avoid a shared uniqueness or UUID requirement between clients and agents.
 
 By allowing the agent to replay or acknowledge the user message as a session update, we have a natural place for the agent to provide both the content and the ID once it is inserted in the session. Ultimately the agent is responsible for session persistence. If there is only one source for IDs, we can continue to treat them as opaque strings that fit well into each agent's implementation.
 
diff --git a/schema/schema.json b/schema/schema.json
@@ -1092,6 +1092,17 @@
             }
           ],
           "description": "A single item of content"
+        },
+        "messageId": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/MessageId"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "A unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started."
         }
       },
       "required": ["content"],
@@ -1983,6 +1994,10 @@
       "required": ["name", "command", "args", "env"],
       "type": "object"
     },
+    "MessageId": {
+      "description": "Unique identifier for a message within a session.",
+      "type": "string"
+    },
     "NewSessionRequest": {
       "description": "Request parameters for creating a new session.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/session-setup#creating-a-session)",
       "properties": {
diff --git a/schema/schema.unstable.json b/schema/schema.unstable.json
@@ -1854,7 +1854,7 @@
               "type": "null"
             }
           ],
-          "description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started."
+          "description": "A unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started."
         }
       },
       "required": ["content"],
diff --git a/src/rpc.rs b/src/rpc.rs
@@ -328,7 +328,6 @@ mod tests {
                             text: "Hello".to_string(),
                             meta: None,
                         }),
-                        #[cfg(feature = "unstable_message_id")]
                         message_id: None,
                         meta: None,
                     }),
diff --git a/src/v1/client.rs b/src/v1/client.rs
diff --git a/src/v2/client.rs b/src/v2/client.rs
diff --git a/src/v2/conversion.rs b/src/v2/conversion.rs
