diff --git a/agent-client-protocol-schema/src/v2/agent.rs b/agent-client-protocol-schema/src/v2/agent.rs index 3277ebe14..41553001f 100644 --- a/agent-client-protocol-schema/src/v2/agent.rs +++ b/agent-client-protocol-schema/src/v2/agent.rs @@ -1425,6 +1425,9 @@ impl NewSessionRequest { /// Updates may arrive before or after this response. Clients MUST NOT overwrite /// an already-reported state when the response arrives. /// +/// An Agent whose new session is not `idle` MUST send the session's +/// `state_update` after this response. +/// /// See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v2/session-setup#creating-a-session) #[serde_as] #[skip_serializing_none] diff --git a/docs/protocol/v2/draft/prompt-lifecycle.mdx b/docs/protocol/v2/draft/prompt-lifecycle.mdx index 5021ffd25..a92111c33 100644 --- a/docs/protocol/v2/draft/prompt-lifecycle.mdx +++ b/docs/protocol/v2/draft/prompt-lifecycle.mdx @@ -1324,6 +1324,7 @@ New sessions default to `idle` until a state update reports otherwise. State updates may arrive before or after the `session/new` response. Clients **MUST NOT** overwrite an already-reported state when the response arrives. A separate initial idle notification is optional and does not represent completion. +An Agent whose new session is not `idle` sends that state after the response. See [Initial session state](/protocol/v2/draft/session-setup#initial-session-state). `session/resume` does not imply `idle`. The Agent **MUST** send a snapshot of foreground state after resuming, following any requested history replay and diff --git a/docs/protocol/v2/draft/schema.mdx b/docs/protocol/v2/draft/schema.mdx index 511d9ab04..b95390c3b 100644 --- a/docs/protocol/v2/draft/schema.mdx +++ b/docs/protocol/v2/draft/schema.mdx @@ -1060,6 +1060,9 @@ New sessions default to `idle` until a state update reports otherwise. Updates may arrive before or after this response. Clients MUST NOT overwrite an already-reported state when the response arrives. +An Agent whose new session is not `idle` MUST send the session's +`state_update` after this response. + See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v2/draft/session-setup#creating-a-session) **Type:** Object diff --git a/docs/protocol/v2/draft/session-setup.mdx b/docs/protocol/v2/draft/session-setup.mdx index eb995bd3a..c7654a51b 100644 --- a/docs/protocol/v2/draft/session-setup.mdx +++ b/docs/protocol/v2/draft/session-setup.mdx @@ -102,7 +102,7 @@ may arrive before or after the `session/new` response. Clients **MUST NOT** overwrite an already-reported state when the response arrives. An optional initial idle notification is a snapshot, not a completed turn. -Agents **SHOULD** put initial state in the `session/new` response rather than sending notifications before it. For `configOptions` and `availableCommands`, the response is required, as described below. Agents **SHOULD NOT** send session-scoped requests, such as permission requests or elicitations, before the response, because the Client cannot yet show them for that session. While a `session/new` is pending, Clients **MAY** buffer notifications for a `sessionId` they don't recognize and apply them in order once the response arrives, or drop them. Agents cannot rely on such notifications being seen. +Agents **SHOULD** put initial state in the `session/new` response rather than sending notifications before it. For `configOptions` and `availableCommands`, the response is required, as described below. Agents **SHOULD NOT** send session-scoped requests, such as permission requests or elicitations, before the response, because the Client cannot yet show them for that session. While a `session/new` is pending, Clients **MAY** buffer notifications for a `sessionId` they don't recognize and apply them in order once the response arrives, or drop them. Agents cannot rely on such notifications being seen. An Agent whose new session is not `idle`, for example because it started work when the session was created, **MUST** send the session's `state_update` after the response. `session/resume` does not imply idle: an existing session may still be running or waiting for user action. See [Current-State Synchronization](#current-state-synchronization). diff --git a/docs/protocol/v2/prompt-lifecycle.mdx b/docs/protocol/v2/prompt-lifecycle.mdx index 59364d102..6e9b1920c 100644 --- a/docs/protocol/v2/prompt-lifecycle.mdx +++ b/docs/protocol/v2/prompt-lifecycle.mdx @@ -1097,6 +1097,7 @@ New sessions default to `idle` until a state update reports otherwise. State updates may arrive before or after the `session/new` response. Clients **MUST NOT** overwrite an already-reported state when the response arrives. A separate initial idle notification is optional and does not represent completion. +An Agent whose new session is not `idle` sends that state after the response. See [Initial session state](/protocol/v2/session-setup#initial-session-state). `session/resume` does not imply `idle`. The Agent **MUST** send a snapshot of foreground state after resuming, following any requested history replay and diff --git a/docs/protocol/v2/schema.mdx b/docs/protocol/v2/schema.mdx index b88ca2ef1..a69b5e82f 100644 --- a/docs/protocol/v2/schema.mdx +++ b/docs/protocol/v2/schema.mdx @@ -524,6 +524,9 @@ New sessions default to `idle` until a state update reports otherwise. Updates may arrive before or after this response. Clients MUST NOT overwrite an already-reported state when the response arrives. +An Agent whose new session is not `idle` MUST send the session's +`state_update` after this response. + See protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v2/session-setup#creating-a-session) **Type:** Object diff --git a/docs/protocol/v2/session-setup.mdx b/docs/protocol/v2/session-setup.mdx index e0581b4ff..1faa0d1a7 100644 --- a/docs/protocol/v2/session-setup.mdx +++ b/docs/protocol/v2/session-setup.mdx @@ -102,7 +102,7 @@ may arrive before or after the `session/new` response. Clients **MUST NOT** overwrite an already-reported state when the response arrives. An optional initial idle notification is a snapshot, not a completed turn. -Agents **SHOULD** put initial state in the `session/new` response rather than sending notifications before it. For `configOptions` and `availableCommands`, the response is required, as described below. Agents **SHOULD NOT** send session-scoped requests, such as permission requests or elicitations, before the response, because the Client cannot yet show them for that session. While a `session/new` is pending, Clients **MAY** buffer notifications for a `sessionId` they don't recognize and apply them in order once the response arrives, or drop them. Agents cannot rely on such notifications being seen. +Agents **SHOULD** put initial state in the `session/new` response rather than sending notifications before it. For `configOptions` and `availableCommands`, the response is required, as described below. Agents **SHOULD NOT** send session-scoped requests, such as permission requests or elicitations, before the response, because the Client cannot yet show them for that session. While a `session/new` is pending, Clients **MAY** buffer notifications for a `sessionId` they don't recognize and apply them in order once the response arrives, or drop them. Agents cannot rely on such notifications being seen. An Agent whose new session is not `idle`, for example because it started work when the session was created, **MUST** send the session's `state_update` after the response. `session/resume` does not imply idle: an existing session may still be running or waiting for user action. See [Current-State Synchronization](#current-state-synchronization). diff --git a/schema/v2/schema.json b/schema/v2/schema.json index 8be85eec4..e99fbcdc6 100644 --- a/schema/v2/schema.json +++ b/schema/v2/schema.json @@ -3478,7 +3478,7 @@ "x-method": "auth/logout" }, "NewSessionResponse": { - "description": "Response from creating a new session.\n\nNew sessions default to `idle` until a state update reports otherwise.\nUpdates may arrive before or after this response. Clients MUST NOT overwrite\nan already-reported state when the response arrives.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v2/session-setup#creating-a-session)", + "description": "Response from creating a new session.\n\nNew sessions default to `idle` until a state update reports otherwise.\nUpdates may arrive before or after this response. Clients MUST NOT overwrite\nan already-reported state when the response arrives.\n\nAn Agent whose new session is not `idle` MUST send the session's\n`state_update` after this response.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v2/session-setup#creating-a-session)", "type": "object", "properties": { "sessionId": { diff --git a/schema/v2/schema.unstable.json b/schema/v2/schema.unstable.json index 283530005..70087fcde 100644 --- a/schema/v2/schema.unstable.json +++ b/schema/v2/schema.unstable.json @@ -4210,7 +4210,7 @@ "required": ["label"] }, "NewSessionResponse": { - "description": "Response from creating a new session.\n\nNew sessions default to `idle` until a state update reports otherwise.\nUpdates may arrive before or after this response. Clients MUST NOT overwrite\nan already-reported state when the response arrives.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v2/draft/session-setup#creating-a-session)", + "description": "Response from creating a new session.\n\nNew sessions default to `idle` until a state update reports otherwise.\nUpdates may arrive before or after this response. Clients MUST NOT overwrite\nan already-reported state when the response arrives.\n\nAn Agent whose new session is not `idle` MUST send the session's\n`state_update` after this response.\n\nSee protocol docs: [Creating a Session](https://agentclientprotocol.com/protocol/v2/draft/session-setup#creating-a-session)", "type": "object", "properties": { "sessionId": {