Skip to content

Commit 8b2170d

Browse files
benbrandtbenbrandt
authored
docs(protocol): list elicitation methods and definition renames in the v2 migration guide (#2528)
The method table now includes elicitation/create and elicitation/complete. The codegen rename paragraph adds ClientAuthCapabilities, gives examples of definitions renamed or removed along with wire changes, and says the lists aren't exhaustive.
1 parent 740738b commit 8b2170d

1 file changed

Lines changed: 23 additions & 21 deletions

File tree

‎docs/protocol/v2/migration.mdx‎

Lines changed: 23 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -35,26 +35,28 @@ v2 keeps the underlying JSON-RPC framing, except that request IDs can no longer
3535

3636
### Method changes
3737

38-
| v1 method | v2 |
39-
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
40-
| `initialize` | Unchanged name. Params and result restructured |
41-
| `authenticate` | Renamed to `auth/login` for protocol-driven authentication methods |
42-
| `logout` (gated by `agentCapabilities.auth.logout`) | Renamed to `auth/logout`. Required when `authMethods` is non-empty. No logout capability marker |
43-
| `session/new` | `mcpServers` now optional. Response no longer includes `modes` |
44-
| `session/load` | **Removed**. Use `session/resume` with `"replayFrom": { "type": "start" }` |
45-
| `session/resume` | Gains optional `replayFrom`. Required (no capability marker) |
46-
| `session/list` | Required. No capability |
47-
| `session/close` | Required. No capability |
48-
| `session/delete` | Unchanged. Still optional via `session.delete` capability |
49-
| `session/prompt` | Unchanged shape. **Response semantics redesigned** (see [Prompt lifecycle](#the-new-prompt-lifecycle)) |
50-
| `session/cancel` | Unchanged name. Completion now reported via `state_update` instead of the prompt response |
51-
| `session/set_mode` | **Removed**. Use `session/set_config_option` |
52-
| `session/set_config_option` | Required when the Agent advertises config options. No capability |
53-
| `session/request_permission` | Unchanged name. Params restructured (required `title`, optional `subject`) |
54-
| `session/update` | Unchanged name. Update variants changed (see below) |
55-
| `fs/read_text_file`, `fs/write_text_file` | **Removed** |
56-
| `terminal/create`, `terminal/output`, `terminal/release`, `terminal/wait_for_exit`, `terminal/kill` | **Removed** |
57-
| `$/cancel_request` | Unchanged, except for an inserted `session/prompt` (see Cancellation) |
38+
| v1 method | v2 |
39+
| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
40+
| `initialize` | Unchanged name. Params and result restructured |
41+
| `authenticate` | Renamed to `auth/login` for protocol-driven authentication methods |
42+
| `logout` (gated by `agentCapabilities.auth.logout`) | Renamed to `auth/logout`. Required when `authMethods` is non-empty. No logout capability marker |
43+
| `session/new` | `mcpServers` now optional. Response no longer includes `modes` |
44+
| `session/load` | **Removed**. Use `session/resume` with `"replayFrom": { "type": "start" }` |
45+
| `session/resume` | Gains optional `replayFrom`. Required (no capability marker) |
46+
| `session/list` | Required. No capability |
47+
| `session/close` | Required. No capability |
48+
| `session/delete` | Unchanged. Still optional via `session.delete` capability |
49+
| `session/prompt` | Unchanged shape. **Response semantics redesigned** (see [Prompt lifecycle](#the-new-prompt-lifecycle)) |
50+
| `session/cancel` | Unchanged name. Completion now reported via `state_update` instead of the prompt response |
51+
| `session/set_mode` | **Removed**. Use `session/set_config_option` |
52+
| `session/set_config_option` | Required when the Agent advertises config options. No capability |
53+
| `session/request_permission` | Unchanged name. Params restructured (required `title`, optional `subject`) |
54+
| `session/update` | Unchanged name. Update variants changed (see below) |
55+
| `elicitation/create` | Unchanged shape. Exactly one of `sessionId` or `requestId` is required; session-scoped requests follow the foreground-state contract (`requires_action`); an unknown action is handled as `cancel` |
56+
| `elicitation/complete` | Unchanged |
57+
| `fs/read_text_file`, `fs/write_text_file` | **Removed** |
58+
| `terminal/create`, `terminal/output`, `terminal/release`, `terminal/wait_for_exit`, `terminal/kill` | **Removed** |
59+
| `$/cancel_request` | Unchanged, except for an inserted `session/prompt` (see Cancellation) |
5860

5961
### `session/update` variant changes
6062

@@ -863,7 +865,7 @@ v2 applies one naming rule across the schema: a field that identifies a protocol
863865

864866
New entities introduced in v2 follow the same rule (`messageId` on messages, `planId` on plans).
865867

866-
A few schema definition names also changed without any wire-format change, which matters only to schema-codegen consumers: the `session/update` and `session/cancel` payload types are now `UpdateSessionNotification` and `CancelSessionNotification`, and the auth request/response types follow the new method names (`LoginAuthRequest`/`LoginAuthResponse`, `LogoutAuthRequest`/`LogoutAuthResponse`).
868+
A few schema definition names also changed without any wire-format change, which matters only to schema-codegen consumers: the `session/update` and `session/cancel` payload types are now `UpdateSessionNotification` and `CancelSessionNotification`, the auth request/response types follow the new method names (`LoginAuthRequest`/`LoginAuthResponse`, `LogoutAuthRequest`/`LogoutAuthResponse`), and the Client auth capability type is now `ClientAuthCapabilities`. Definitions tied to wire changes are renamed or removed along with them, for example `UnstructuredCommandInput` → `TextCommandInput`, `Plan` → `PlanUpdate`, `ToolCall` → `ToolCallUpdate`, and `McpServerSse` removed. These lists are not exhaustive; compare the `$defs` of the two schemas for the complete set.
867869

868870
## Extensibility and forward compatibility
869871

0 commit comments

Comments
 (0)