Skip to content

docs(unstable-v2): list all SessionUpdate variants on the prompt lifecycle page #1891

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tarikermis wants to merge 1 commit into
base: main
Choose a base branch
from
+65 −0
Open

docs(unstable-v2): list all SessionUpdate variants on the prompt lifecycle page #1891

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions docs/protocol/v2/draft/prompt-lifecycle.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,13 @@ When foreground work starts or resumes, the Agent **MUST** send a `state_update`

The language model **MAY** respond with text content, tool calls, or both.

<Note>
This walkthrough covers the `session/update` variants most common in a prompt
turn. It is not the full set: [Session Update
Variants](#session-update-variants) lists every variant the schema defines in
this version.
</Note>

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:

```json expandable
Expand Down Expand Up @@ -439,6 +446,32 @@ The Agent sends the tool results back to the language model as another request.

The cycle returns to [step 3](#3-agent-reports-output), continuing until the language model completes its response without requesting additional tool calls or foreground work is stopped by the Agent or cancelled by the Client.

## Session Update Variants

The `SessionUpdate` union defines the following variants in this version. The walkthrough above covers the ones most common in a prompt turn; the rest report session activity that is not tied to model output and can arrive whenever the underlying state changes, including before or between prompts.

| `sessionUpdate` | Reports | Key fields |
| --------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `user_message` | A user message created or updated; upsert keyed by `messageId` | `messageId`, optional `content` |
| `user_message_chunk` | A chunk of a user message being streamed | `messageId`, `content` |
| `agent_message` | An agent message created or updated; upsert keyed by `messageId` | `messageId`, optional `content` |
| `agent_message_chunk` | A chunk of the Agent's response being streamed | `messageId`, `content` |
| `agent_thought` | An agent thought created or updated; upsert keyed by `messageId` | `messageId`, optional `content` |
| `agent_thought_chunk` | A chunk of internal reasoning being streamed | `messageId`, `content` |
| `state_update` | The Agent's foreground-work [state](#session-states) changed | `state`; `stopReason`, `usage` when `idle` |
| `plan_update` | A content update for a [plan](/protocol/v2/draft/agent-plan) | `plan` |
| `plan_removed` | A [plan](/protocol/v2/draft/agent-plan#removing-plans) removed by ID (draft unstable schema) | `planId` |
| `tool_call_update` | A [tool call](/protocol/v2/draft/tool-calls) created or updated | `toolCallId`, patch fields such as `status` and `content` |
| `tool_call_content_chunk` | A chunk of [tool-call content](/protocol/v2/draft/tool-calls#streaming-content) being streamed | `toolCallId`, `content` |
| `terminal_update` | An agent-owned [terminal](/protocol/v2/draft/tool-calls#display-only-terminals) created or updated | `terminalId`, optional `command`, `cwd`, `output`, `exitStatus` |
| `terminal_output_chunk` | A chunk of bytes appended to an agent-owned terminal's output | `terminalId`, `data` |
| `available_commands_update` | [Available commands](/protocol/v2/draft/slash-commands) ready or changed | `availableCommands` |
| `config_option_update` | [Session config options](/protocol/v2/draft/session-config-options#from-the-agent) updated | `configOptions` |
| `session_info_update` | [Session metadata](/protocol/v2/draft/session-list#updating-session-metadata) updated | optional `title`, `updatedAt` |
| `usage_update` | [Context window and cost](#session-usage-updates) update | `used`, `size`, optional `cost` |

Variants with `sessionUpdate` values beginning with `_` are implementation-specific extensions, and unknown non-underscore values are reserved for future ACP variants. Receivers that do not recognize a variant preserve its raw payload when storing, replaying, proxying, or forwarding session history, and otherwise ignore it or display it generically. See [Enum and Tagged-Union Variants](/protocol/v2/draft/extensibility#enum-and-tagged-union-variants) and the [`SessionUpdate`](/protocol/v2/draft/schema#sessionupdate) schema reference for full payload definitions.

## Stop Reasons

When an Agent stops foreground work, it must specify the corresponding `StopReason` on an idle `state_update` session update:
Expand Down
32 changes: 32 additions & 0 deletions docs/protocol/v2/prompt-lifecycle.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -158,6 +158,13 @@ When foreground work starts or resumes, the Agent **MUST** send a `state_update`

The language model **MAY** respond with text content, tool calls, or both.

<Note>
This walkthrough covers the `session/update` variants most common in a prompt
turn. It is not the full set: [Session Update
Variants](#session-update-variants) lists every variant the schema defines in
this version.
</Note>

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:

```json expandable
Expand Down Expand Up @@ -441,6 +448,31 @@ The Agent sends the tool results back to the language model as another request.

The cycle returns to [step 3](#3-agent-reports-output), continuing until the language model completes its response without requesting additional tool calls or foreground work is stopped by the Agent or cancelled by the Client.

## Session Update Variants

The `SessionUpdate` union defines the following variants in this version. The walkthrough above covers the ones most common in a prompt turn; the rest report session activity that is not tied to model output and can arrive whenever the underlying state changes, including before or between prompts.

| `sessionUpdate` | Reports | Key fields |
| --------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `user_message` | A user message created or updated; upsert keyed by `messageId` | `messageId`, optional `content` |
| `user_message_chunk` | A chunk of a user message being streamed | `messageId`, `content` |
| `agent_message` | An agent message created or updated; upsert keyed by `messageId` | `messageId`, optional `content` |
| `agent_message_chunk` | A chunk of the Agent's response being streamed | `messageId`, `content` |
| `agent_thought` | An agent thought created or updated; upsert keyed by `messageId` | `messageId`, optional `content` |
| `agent_thought_chunk` | A chunk of internal reasoning being streamed | `messageId`, `content` |
| `state_update` | The Agent's foreground-work [state](#session-states) changed | `state`; `stopReason` when `idle` |
| `plan_update` | A content update for a [plan](/protocol/v2/agent-plan) | `plan` |
| `tool_call_update` | A [tool call](/protocol/v2/tool-calls) created or updated | `toolCallId`, patch fields such as `status` and `content` |
| `tool_call_content_chunk` | A chunk of [tool-call content](/protocol/v2/tool-calls#streaming-content) being streamed | `toolCallId`, `content` |
| `terminal_update` | An agent-owned [terminal](/protocol/v2/tool-calls#display-only-terminals) created or updated | `terminalId`, optional `command`, `cwd`, `output`, `exitStatus` |
| `terminal_output_chunk` | A chunk of bytes appended to an agent-owned terminal's output | `terminalId`, `data` |
| `available_commands_update` | [Available commands](/protocol/v2/slash-commands) ready or changed | `availableCommands` |
| `config_option_update` | [Session config options](/protocol/v2/session-config-options#from-the-agent) updated | `configOptions` |
| `session_info_update` | [Session metadata](/protocol/v2/session-list#updating-session-metadata) updated | optional `title`, `updatedAt` |
| `usage_update` | [Context window and cost](#session-usage-updates) update | `used`, `size`, optional `cost` |

Variants with `sessionUpdate` values beginning with `_` are implementation-specific extensions, and unknown non-underscore values are reserved for future ACP variants. Receivers that do not recognize a variant preserve its raw payload when storing, replaying, proxying, or forwarding session history, and otherwise ignore it or display it generically. See [Enum and Tagged-Union Variants](/protocol/v2/extensibility#enum-and-tagged-union-variants) and the [`SessionUpdate`](/protocol/v2/schema#sessionupdate) schema reference for full payload definitions.

## Stop Reasons

When an Agent stops foreground work, it must specify the corresponding `StopReason` on an idle `state_update` session update:
Expand Down