From b33dcbeaffc33c07e5790da02aa980afdb0b51fb Mon Sep 17 00:00:00 2001 From: Som Tripathi Date: Sun, 2 Aug 2026 23:19:03 -0500 Subject: [PATCH] docs: clarify the session/update variant set is not exhaustive The v1 prompt-turn page walks a turn through five session/update variants while schema/v1/schema.json defines eleven, and nothing on the page marks the walkthrough as partial. Point at the SessionUpdate schema reference as the authoritative list, and cover unrecognized variants on the extensibility page. Refs #1694 --- docs/protocol/v1/draft/extensibility.mdx | 4 ++++ docs/protocol/v1/draft/prompt-turn.mdx | 7 +++++++ docs/protocol/v1/extensibility.mdx | 4 ++++ docs/protocol/v1/prompt-turn.mdx | 7 +++++++ 4 files changed, 22 insertions(+) diff --git a/docs/protocol/v1/draft/extensibility.mdx b/docs/protocol/v1/draft/extensibility.mdx index 314410132..8046050e5 100644 --- a/docs/protocol/v1/draft/extensibility.mdx +++ b/docs/protocol/v1/draft/extensibility.mdx @@ -132,3 +132,7 @@ Implementations **SHOULD** use the `_meta` field in capability objects to advert ``` This allows implementations to negotiate custom features during initialization without breaking compatibility with standard Clients and Agents. + +## Unrecognized Session Update Variants + +Every `session/update` notification carries a `sessionUpdate` field that identifies the variant. Future protocol versions may define new variants. Clients are encouraged to ignore variants they do not recognize rather than treating them as errors. The [`SessionUpdate`](/protocol/v1/draft/schema#sessionupdate) schema reference lists the variants defined in this version. diff --git a/docs/protocol/v1/draft/prompt-turn.mdx b/docs/protocol/v1/draft/prompt-turn.mdx index 3a5d3e308..ef3145240 100644 --- a/docs/protocol/v1/draft/prompt-turn.mdx +++ b/docs/protocol/v1/draft/prompt-turn.mdx @@ -105,6 +105,13 @@ Upon receiving the prompt request, the Agent processes the user's message and se The Agent reports the model's output to the Client via `session/update` notifications. This may include the Agent's plan for accomplishing the task: + + This page walks through the `session/update` variants most common in a prompt + turn. It is not the full set. See the + [`SessionUpdate`](/protocol/v1/draft/schema#sessionupdate) schema reference + for every variant defined in this version. + + ```json expandable { "jsonrpc": "2.0", diff --git a/docs/protocol/v1/extensibility.mdx b/docs/protocol/v1/extensibility.mdx index 314410132..3515b40e5 100644 --- a/docs/protocol/v1/extensibility.mdx +++ b/docs/protocol/v1/extensibility.mdx @@ -132,3 +132,7 @@ Implementations **SHOULD** use the `_meta` field in capability objects to advert ``` This allows implementations to negotiate custom features during initialization without breaking compatibility with standard Clients and Agents. + +## Unrecognized Session Update Variants + +Every `session/update` notification carries a `sessionUpdate` field that identifies the variant. Future protocol versions may define new variants. Clients are encouraged to ignore variants they do not recognize rather than treating them as errors. The [`SessionUpdate`](/protocol/v1/schema#sessionupdate) schema reference lists the variants defined in this version. diff --git a/docs/protocol/v1/prompt-turn.mdx b/docs/protocol/v1/prompt-turn.mdx index d459f55b8..0fe5ba9ed 100644 --- a/docs/protocol/v1/prompt-turn.mdx +++ b/docs/protocol/v1/prompt-turn.mdx @@ -105,6 +105,13 @@ Upon receiving the prompt request, the Agent processes the user's message and se The Agent reports the model's output to the Client via `session/update` notifications. This may include the Agent's plan for accomplishing the task: + + This page walks through the `session/update` variants most common in a prompt + turn. It is not the full set. See the + [`SessionUpdate`](/protocol/v1/schema#sessionupdate) schema reference for + every variant defined in this version. + + ```json expandable { "jsonrpc": "2.0",