feat(schema): stabilize deleteSession (#168)

* Update OpenAPI TypeScript generator dependencies

* feat(schema): stabilize deleteSession

Update schema for v0.13.6 protocol changes

* Stabilize session delete and logout docs

Author: benbrandt

package-lock.json

@@ -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",

package.json

@@ -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"
@@ -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"
                 },
                 {
@@ -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.",
@@ -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,
@@ -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,
@@ -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": {
@@ -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": {
@@ -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"],
@@ -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": {
@@ -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,
@@ -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",
@@ -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,
@@ -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"

schema/schema.json

@@ -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();
 

scripts/generate.js

@@ -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: {
@@ -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<
@@ -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<
@@ -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>;
   /**
@@ -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.

src/acp.ts

@@ -110,6 +110,7 @@ export type {
   McpServerHttp,
   McpServerSse,
   McpServerStdio,
+  MessageId,
   MessageMcpNotification,
   MessageMcpRequest,
   MessageMcpResponse,