From fbb576ce72299181911d4a3b9e07b65b34b836f8 Mon Sep 17 00:00:00 2001 From: Ben Brandt Date: Wed, 18 Nov 2026 13:52:02 +0100 Subject: [PATCH] docs(unstable-v2): say the Agent owns the reported user message The prompt lifecycle page did not say whether the `user_message` report must match the submitted prompt, and its example dropped the prompt's `resource` block without explanation. - Make the `user_message` example carry the same content as the `session/prompt` example above it. - Say that the Agent owns the inserted message, that its reported `content` can differ from the prompt, and that a Client may keep showing the prompt as it sent it. --- docs/protocol/v2/draft/prompt-lifecycle.mdx | 10 ++++++++++ docs/protocol/v2/prompt-lifecycle.mdx | 10 ++++++++++ 2 files changed, 20 insertions(+) diff --git a/docs/protocol/v2/draft/prompt-lifecycle.mdx b/docs/protocol/v2/draft/prompt-lifecycle.mdx index a92111c33..f83ab6792 100644 --- a/docs/protocol/v2/draft/prompt-lifecycle.mdx +++ b/docs/protocol/v2/draft/prompt-lifecycle.mdx @@ -374,6 +374,14 @@ The Agent **MUST** also report the inserted user message through a `user_message { "type": "text", "text": "Can you analyze this code for potential issues?" + }, + { + "type": "resource", + "resource": { + "uri": "file:///home/user/project/main.py", + "mimeType": "text/x-python", + "text": "def process_data(items):\n for item in items:\n print(item)" + } } ] } @@ -381,6 +389,8 @@ The Agent **MUST** also report the inserted user message through a `user_message } ``` +The Agent owns the inserted message. Its reported `content` usually repeats the submitted `prompt`, as it does here, but it can differ, for example when an adapter reports the message as its runtime recorded it. A Client **MAY** keep showing the prompt as it sent it, although a [replay](/protocol/v2/draft/session-setup#replay-contents) carries the Agent's content. + The Client uses the JSON-RPC response ID to identify its submission, then associates it with `(sessionId, messageId)`. If the message update arrived first, the Client reconciles with that existing message rather than creating a duplicate. Agents **MUST** assign distinct message IDs to distinct inserted submissions, even if their content is identical. Clients must not infer the association from content or arrival order. Insertion is not a promise of durable storage or model consumption. Every inserted input, including a locally handled command, is reported live, but Agents are not required to persist it or retain it for any minimum period. If the message is retained and replayed, the Agent **MUST** use the same ID. See [Resuming Sessions](/protocol/v2/draft/session-setup#resuming-sessions). diff --git a/docs/protocol/v2/prompt-lifecycle.mdx b/docs/protocol/v2/prompt-lifecycle.mdx index 6e9b1920c..f63482395 100644 --- a/docs/protocol/v2/prompt-lifecycle.mdx +++ b/docs/protocol/v2/prompt-lifecycle.mdx @@ -369,6 +369,14 @@ The Agent **MUST** also report the inserted user message through a `user_message { "type": "text", "text": "Can you analyze this code for potential issues?" + }, + { + "type": "resource", + "resource": { + "uri": "file:///home/user/project/main.py", + "mimeType": "text/x-python", + "text": "def process_data(items):\n for item in items:\n print(item)" + } } ] } @@ -376,6 +384,8 @@ The Agent **MUST** also report the inserted user message through a `user_message } ``` +The Agent owns the inserted message. Its reported `content` usually repeats the submitted `prompt`, as it does here, but it can differ, for example when an adapter reports the message as its runtime recorded it. A Client **MAY** keep showing the prompt as it sent it, although a [replay](/protocol/v2/session-setup#replay-contents) carries the Agent's content. + The Client uses the JSON-RPC response ID to identify its submission, then associates it with `(sessionId, messageId)`. If the message update arrived first, the Client reconciles with that existing message rather than creating a duplicate. Agents **MUST** assign distinct message IDs to distinct inserted submissions, even if their content is identical. Clients must not infer the association from content or arrival order. Insertion is not a promise of durable storage or model consumption. Every inserted input, including a locally handled command, is reported live, but Agents are not required to persist it or retain it for any minimum period. If the message is retained and replayed, the Agent **MUST** use the same ID. See [Resuming Sessions](/protocol/v2/session-setup#resuming-sessions).