Skip to content

feat(schema): stabilize deleteSession #168

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

Merged
benbrandt merged 3 commits into from
Jun 5, 2026
Merged

feat(schema): stabilize deleteSession #168

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
83cb249
Update OpenAPI TypeScript generator dependencies
benbrandt Jun 5, 2026
e29f9fd
feat(schema): stabilize deleteSession
benbrandt Jun 5, 2026
f1ed72d
Stabilize session delete and logout docs
benbrandt Jun 5, 2026
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
557 changes: 295 additions & 262 deletions package-lock.json
View file
Open in desktop

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@
},
"devDependencies": {
"@eslint/js": "^10.0.1",
"@hey-api/openapi-ts": "^0.97.0",
"@hey-api/openapi-ts": "^0.98.0",
"@types/node": "^25.5.0",
"@typescript-eslint/eslint-plugin": "^8.57.1",
"@typescript-eslint/parser": "^8.57.1",
Expand Down
83 changes: 54 additions & 29 deletions schema/schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1025,7 +1025,7 @@
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNES (Next Edit Suggestions) capabilities supported by the client.",
"x-deserialize-default-on-error": true
},
"planCapabilities": {
"plan": {
"anyOf": [
{
"$ref": "#/$defs/PlanCapabilities"
Expand Down Expand Up @@ -1312,7 +1312,7 @@
"$ref": "#/$defs/DeleteSessionRequest"
}
],
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nDeletes an existing session from `session/list`.\n\nThis method is only available if the agent advertises the `sessionCapabilities.delete` capability.",
"description": "Deletes an existing session from `session/list`.\n\nThis method is only available if the agent advertises the `sessionCapabilities.delete` capability.",
"title": "DeleteSessionRequest"
},
{
Expand Down Expand Up @@ -1846,15 +1846,22 @@
"description": "A single item of content"
},
"messageId": {
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started.\nBoth clients and agents MUST use UUID format for message IDs.",
"type": ["string", "null"]
"anyOf": [
{
"$ref": "#/$defs/MessageId"
},
{
"type": "null"
}
],
"description": "A unique identifier for the message this chunk belongs to.\n\nAll chunks belonging to the same message share the same `messageId`.\nA change in `messageId` indicates a new message has started."
}
},
"required": ["content"],
"type": "object"
},
"Cost": {
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCost information for a session.",
"description": "Cost information for a session.",
"properties": {
"amount": {
"description": "Total cumulative cost for session.",
Expand Down Expand Up @@ -2069,7 +2076,7 @@
"type": "object"
},
"DeleteSessionRequest": {
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nRequest parameters for deleting an existing session from `session/list`.\n\nOnly available if the Agent supports the `sessionCapabilities.delete` capability.",
"description": "Request parameters for deleting an existing session from `session/list`.\n\nOnly available if the Agent supports the `sessionCapabilities.delete` capability.",
"properties": {
"_meta": {
"additionalProperties": true,
Expand All @@ -2091,7 +2098,7 @@
"x-side": "agent"
},
"DeleteSessionResponse": {
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nResponse from deleting a session.",
"description": "Response from deleting a session.",
"properties": {
"_meta": {
"additionalProperties": true,
Expand Down Expand Up @@ -3726,6 +3733,10 @@
"required": ["name", "command", "args", "env"],
"type": "object"
},
"MessageId": {
"description": "Unique identifier for a message within a session.",
"type": "string"
},
"MessageMcpNotification": {
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nNotification parameters for `mcp/message`.\n\nThis is used when the wrapped MCP message is a notification and the outer JSON-RPC\nenvelope has no `id`.",
"properties": {
Expand Down Expand Up @@ -5295,10 +5306,6 @@
"description": "The _meta property is reserved by ACP to allow clients and agents to attach additional\nmetadata to their interactions. Implementations MUST NOT make assumptions about values at\nthese keys.\n\nSee protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/extensibility)",
"type": ["object", "null"]
},
"messageId": {
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nA client-generated unique identifier for this user message.\n\nIf provided, the Agent SHOULD echo this value as `userMessageId` in the\n[`PromptResponse`] to confirm it was recorded.\nBoth clients and agents MUST use UUID format for message IDs.",
"type": ["string", "null"]
},
"prompt": {
"description": "The blocks of content that compose the user's message.\n\nAs a baseline, the Agent MUST support [`ContentBlock::Text`] and [`ContentBlock::ResourceLink`],\nwhile other variants are optionally enabled via [`PromptCapabilities`].\n\nThe Client MUST adapt its interface according to [`PromptCapabilities`].\n\nThe client MAY include referenced pieces of context as either\n[`ContentBlock::Resource`] or [`ContentBlock::ResourceLink`].\n\nWhen available, [`ContentBlock::Resource`] is preferred\nas it avoids extra round-trips and allows the message to include\npieces of context from sources the agent may not have access to.",
"items": {
Expand Down Expand Up @@ -5347,10 +5354,6 @@
],
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nToken usage for this turn (optional).",
"x-deserialize-default-on-error": true
},
"userMessageId": {
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nThe acknowledged user message ID.\n\nIf the client provided a `messageId` in the [`PromptRequest`], the agent echoes it here\nto confirm it was recorded. If the client did not provide one, the agent MAY assign one\nand return it here. Absence of this field indicates the agent did not record a message ID.",
"type": ["string", "null"]
}
},
"required": ["stopReason"],
Expand Down Expand Up @@ -5895,7 +5898,7 @@
"type": "null"
}
],
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nWhether the agent supports `session/delete`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports deleting sessions from `session/list`.",
"description": "Whether the agent supports `session/delete`.\n\nOptional. Omitted or `null` both mean the agent does not advertise support.\nSupplying `{}` means the agent supports deleting sessions from `session/list`.",
"x-deserialize-default-on-error": true
},
"fork": {
Expand Down Expand Up @@ -6177,7 +6180,7 @@
"type": "string"
},
"SessionDeleteCapabilities": {
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nCapabilities for the `session/delete` method.\n\nSupplying `{}` means the agent supports deleting sessions from `session/list`.",
"description": "Capabilities for the `session/delete` method.\n\nSupplying `{}` means the agent supports deleting sessions from `session/list`.",
"properties": {
"_meta": {
"additionalProperties": true,
Expand Down Expand Up @@ -6572,7 +6575,7 @@
"$ref": "#/$defs/UsageUpdate"
}
],
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nContext window and cost update for the session.",
"description": "Context window and cost update for the session.",
"properties": {
"sessionUpdate": {
"const": "usage_update",
Expand Down Expand Up @@ -7604,7 +7607,7 @@
"type": "object"
},
"UsageUpdate": {
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or changed at any point.\n\nContext window and cost update for a session.",
"description": "Context window and cost update for a session.",
"properties": {
"_meta": {
"additionalProperties": true,
Expand Down Expand Up @@ -7826,19 +7829,41 @@
"type": "object"
},
{
"anyOf": [
{
"allOf": [
"description": "A message (request, response, or notification) with `\"jsonrpc\": \"2.0\"` specified as\n[required by JSON-RPC 2.0 Specification][1].\n\n[1]: https://www.jsonrpc.org/specification#compatibility",
"properties": {
"jsonrpc": {
"enum": ["2.0"],
"type": "string"
},
"method": {
"type": "string"
},
"params": {
"anyOf": [
{
"$ref": "#/$defs/CancelRequestNotification"
"anyOf": [
{
"allOf": [
{
"$ref": "#/$defs/CancelRequestNotification"
}
],
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or\nchanged at any point.\n\nCancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MUST cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)",
"title": "CancelRequestNotification"
}
],
"description": "General protocol-level notifications that all sides are expected to\nimplement.\n\nNotifications whose methods start with '$/' are messages which\nare protocol implementation dependent and might not be implementable in all\nclients or agents. For example if the implementation uses a single threaded\nsynchronous programming language then there is little it can do to react to\na `$/cancel_request` notification. If an agent or client receives\nnotifications starting with '$/' it is free to ignore the notification.\n\nNotifications do not expect a response."
},
{
"type": "null"
}
],
"description": "**UNSTABLE**\n\nThis capability is not part of the spec yet, and may be removed or\nchanged at any point.\n\nCancels an ongoing request.\n\nThis is a notification sent by the side that sent a request to cancel that request.\n\nUpon receiving this notification, the receiver:\n\n1. MUST cancel the corresponding request activity and all nested activities\n2. MAY send any pending notifications.\n3. MUST send one of these responses for the original request:\n - Valid response with appropriate data (partial results or cancellation marker)\n - Error response with code `-32800` (Cancelled)\n\nSee protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/cancellation)",
"title": "CancelRequestNotification"
]
}
],
"description": "General protocol-level notifications that all sides are expected to\nimplement.\n\nNotifications whose methods start with '$/' are messages which\nare protocol implementation dependent and might not be implementable in all\nclients or agents. For example if the implementation uses a single threaded\nsynchronous programming language then there is little it can do to react to\na `$/cancel_request` notification. If an agent or client receives\nnotifications starting with '$/' it is free to ignore the notification.\n\nNotifications do not expect a response.",
"title": "ProtocolLevel"
},
"required": ["jsonrpc", "method"],
"title": "ProtocolLevel",
"type": "object",
"x-docs-ignore": true
}
],
"title": "Agent Client Protocol"
Expand Down
2 changes: 1 addition & 1 deletion scripts/generate.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import * as fs from "fs/promises";
import { dirname } from "path";
import * as prettier from "prettier";

const CURRENT_SCHEMA_RELEASE = "v0.13.5";
const CURRENT_SCHEMA_RELEASE = "v0.13.6";

await main();

Expand Down
33 changes: 6 additions & 27 deletions src/acp.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,11 +86,11 @@ export class AgentSideConnection {
return agent.listSessions(validatedParams);
}
case schema.AGENT_METHODS.session_delete: {
if (!agent.unstable_deleteSession) {
if (!agent.deleteSession) {
throw RequestError.methodNotFound(method);
}
const validatedParams = validate.zDeleteSessionRequest.parse(params);
const result = await agent.unstable_deleteSession(validatedParams);
const result = await agent.deleteSession(validatedParams);
return result ?? {};
}
case schema.AGENT_METHODS.session_fork: {
Expand Down Expand Up @@ -827,17 +827,11 @@ export class ClientSideConnection implements Agent {
}

/**
* **UNSTABLE**
*
* This capability is not part of the spec yet, and may be removed or changed at any point.
*
* Deletes an existing session returned by `session/list`.
*
* This method is only available if the agent advertises the `sessionCapabilities.delete` capability.
*
* @experimental
*/
unstable_deleteSession(
deleteSession(
params: schema.DeleteSessionRequest,
): Promise<schema.DeleteSessionResponse> {
return this.connection.sendRequest<
Expand Down Expand Up @@ -1003,11 +997,7 @@ export class ClientSideConnection implements Agent {
}

/**
* Terminates the current authenticated session.
*
* **UNSTABLE**: This capability is not part of the spec yet, and may be removed or changed at any point.
*
* @experimental
* Logout of the current authentication method.
*/
logout(params: schema.LogoutRequest): Promise<schema.LogoutResponse> {
return this.connection.sendRequest<
Expand Down Expand Up @@ -1998,17 +1988,11 @@ export interface Agent {
params: schema.ListSessionsRequest,
): Promise<schema.ListSessionsResponse>;
/**
* **UNSTABLE**
*
* This capability is not part of the spec yet, and may be removed or changed at any point.
*
* Deletes an existing session returned by `session/list`.
*
* This method is only available if the agent advertises the `sessionCapabilities.delete` capability.
*
* @experimental
*/
unstable_deleteSession?(
deleteSession?(
params: schema.DeleteSessionRequest,
): Promise<schema.DeleteSessionResponse | void>;
/**
Expand Down Expand Up @@ -2120,13 +2104,8 @@ export interface Agent {
params: schema.DisableProviderRequest,
): Promise<schema.DisableProviderResponse | void>;
/**
* Terminates the current authenticated session.
*
* **UNSTABLE**: This capability is not part of the spec yet, and may be removed or changed at any point.
*
* @experimental
* Logout of the current authentication method.
*/

logout?(params: schema.LogoutRequest): Promise<schema.LogoutResponse | void>;
/**
* Processes a user prompt within a session.
Expand Down
1 change: 1 addition & 0 deletions src/schema/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,7 @@ export type {
McpServerHttp,
McpServerSse,
McpServerStdio,
MessageId,
MessageMcpNotification,
MessageMcpRequest,
MessageMcpResponse,
Expand Down
Loading