Add terminal/kill method (#53)

Co-authored-by: Bennet Bo Fenner <bennetbo@gmx.de>

Author: agu-z

AGENTS.md

@@ -21,7 +21,7 @@ All paths in the protocol should be absolute
 - Add constants for the method names
 - Add variants to {Agent|Client}{Request|Response} enums
 - Add the methods to the Client/Agent impl of {Agent|Client}SideConnection in rust/acp.rs
-- Handle the method in the decoders
+- Handle the new method in the `Side::decode_request`/`Side::decode_notification` implementation
 - Handle the new request in the blanket impl of MessageHandler<{Agent|Client}Side>
 - Add the method to markdown_generator.rs SideDocs functions
 - Run `npm run generate` and fix any issues that appear

rust/acp.rs

@@ -254,6 +254,10 @@ impl Side for ClientSide {
                 .map(AgentRequest::TerminalOutputRequest)
                 .map_err(Into::into),
             #[cfg(feature = "unstable")]
+            TERMINAL_KILL_METHOD_NAME => serde_json::from_str(params.get())
+                .map(AgentRequest::KillTerminalRequest)
+                .map_err(Into::into),
+            #[cfg(feature = "unstable")]
             TERMINAL_RELEASE_METHOD_NAME => serde_json::from_str(params.get())
                 .map(AgentRequest::ReleaseTerminalRequest)
                 .map_err(Into::into),
@@ -315,6 +319,11 @@ impl<T: Client> MessageHandler<ClientSide> for T {
                 let response = self.wait_for_terminal_exit(args).await?;
                 Ok(ClientResponse::WaitForTerminalExitResponse(response))
             }
+            #[cfg(feature = "unstable")]
+            AgentRequest::KillTerminalRequest(args) => {
+                self.kill_terminal(args).await?;
+                Ok(ClientResponse::KillTerminalResponse)
+            }
         }
     }
 
@@ -468,6 +477,16 @@ impl Client for AgentSideConnection {
             .await
     }
 
+    #[cfg(feature = "unstable")]
+    async fn kill_terminal(&self, arguments: KillTerminalRequest) -> Result<(), Error> {
+        self.conn
+            .request(
+                TERMINAL_KILL_METHOD_NAME,
+                Some(AgentRequest::KillTerminalRequest(arguments)),
+            )
+            .await
+    }
+
     async fn session_notification(&self, notification: SessionNotification) -> Result<(), Error> {
         self.conn.notify(
             SESSION_UPDATE_NOTIFICATION,

rust/client.rs

@@ -111,6 +111,13 @@ pub trait Client {
         &self,
         args: WaitForTerminalExitRequest,
     ) -> impl Future<Output = Result<WaitForTerminalExitResponse, Error>>;
+
+    /// **UNSTABLE**
+    ///
+    /// This method is not part of the spec, and may be removed or changed at any point.
+    #[doc(hidden)]
+    #[cfg(feature = "unstable")]
+    fn kill_terminal(&self, args: KillTerminalRequest) -> impl Future<Output = Result<(), Error>>;
 }
 
 // Session updates
@@ -353,6 +360,15 @@ pub struct ReleaseTerminalRequest {
     pub terminal_id: TerminalId,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[schemars(extend("x-docs-ignore" = true))]
+#[serde(rename_all = "camelCase")]
+#[cfg(feature = "unstable")]
+pub struct KillTerminalRequest {
+    pub session_id: SessionId,
+    pub terminal_id: TerminalId,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
 #[schemars(extend("x-docs-ignore" = true))]
 #[serde(rename_all = "camelCase")]
@@ -445,6 +461,9 @@ pub struct ClientMethodNames {
     /// Method for waiting for a terminal to finish.
     #[cfg(feature = "unstable")]
     pub terminal_wait_for_exit: &'static str,
+    /// Method for killing a terminal.
+    #[cfg(feature = "unstable")]
+    pub terminal_kill: &'static str,
 }
 
 /// Constant containing all client method names.
@@ -461,6 +480,8 @@ pub const CLIENT_METHOD_NAMES: ClientMethodNames = ClientMethodNames {
     terminal_release: TERMINAL_RELEASE_METHOD_NAME,
     #[cfg(feature = "unstable")]
     terminal_wait_for_exit: TERMINAL_WAIT_FOR_EXIT_METHOD_NAME,
+    #[cfg(feature = "unstable")]
+    terminal_kill: TERMINAL_KILL_METHOD_NAME,
 };
 
 /// Notification name for session updates.
@@ -483,6 +504,9 @@ pub(crate) const TERMINAL_RELEASE_METHOD_NAME: &str = "terminal/release";
 /// Method for waiting for a terminal to finish.
 #[cfg(feature = "unstable")]
 pub(crate) const TERMINAL_WAIT_FOR_EXIT_METHOD_NAME: &str = "terminal/wait_for_exit";
+/// Method for killing a terminal.
+#[cfg(feature = "unstable")]
+pub(crate) const TERMINAL_KILL_METHOD_NAME: &str = "terminal/kill";
 
 /// All possible requests that an agent can send to a client.
 ///
@@ -505,6 +529,8 @@ pub enum AgentRequest {
     ReleaseTerminalRequest(ReleaseTerminalRequest),
     #[cfg(feature = "unstable")]
     WaitForTerminalExitRequest(WaitForTerminalExitRequest),
+    #[cfg(feature = "unstable")]
+    KillTerminalRequest(KillTerminalRequest),
 }
 
 /// All possible responses that a client can send to an agent.
@@ -528,6 +554,8 @@ pub enum ClientResponse {
     ReleaseTerminalResponse,
     #[cfg(feature = "unstable")]
     WaitForTerminalExitResponse(WaitForTerminalExitResponse),
+    #[cfg(feature = "unstable")]
+    KillTerminalResponse,
 }
 
 /// All possible notifications that an agent can send to a client.

rust/example_client.rs

@@ -72,6 +72,14 @@ impl acp::Client for ExampleClient {
         Err(acp::Error::method_not_found())
     }
 
+    #[cfg(feature = "unstable")]
+    async fn kill_terminal(
+        &self,
+        _args: acp::KillTerminalRequest,
+    ) -> anyhow::Result<(), acp::Error> {
+        Err(acp::Error::method_not_found())
+    }
+
     async fn session_notification(
         &self,
         args: acp::SessionNotification,

rust/markdown_generator.rs

@@ -648,6 +648,7 @@ impl SideDocs {
             "terminal/output" => self.client_methods.get("terminal_output").unwrap(),
             "terminal/release" => self.client_methods.get("release_terminal").unwrap(),
             "terminal/wait_for_exit" => self.client_methods.get("wait_for_terminal_exit").unwrap(),
+            "terminal/kill" => self.client_methods.get("kill_terminal").unwrap(),
             _ => panic!("Introduced a method? Add it here :)"),
         }
     }

schema/meta.json

@@ -13,6 +13,7 @@
     "session_request_permission": "session/request_permission",
     "session_update": "session/update",
     "terminal_create": "terminal/create",
+    "terminal_kill": "terminal/kill",
     "terminal_output": "terminal/output",
     "terminal_release": "terminal/release",
     "terminal_wait_for_exit": "terminal/wait_for_exit"

schema/schema.json

@@ -59,6 +59,10 @@
         {
           "$ref": "#/$defs/WaitForTerminalExitRequest",
           "title": "WaitForTerminalExitRequest"
+        },
+        {
+          "$ref": "#/$defs/KillTerminalRequest",
+          "title": "KillTerminalRequest"
         }
       ],
       "description": "All possible requests that an agent can send to a client.\n\nThis enum is used internally for routing RPC requests. You typically won't need\nto use this directly - instead, use the methods on the [`Client`] trait.\n\nThis enum encompasses all method calls from agent to client.",
@@ -281,6 +285,10 @@
         {
           "$ref": "#/$defs/WaitForTerminalExitResponse",
           "title": "WaitForTerminalExitResponse"
+        },
+        {
+          "title": "KillTerminalResponse",
+          "type": "null"
         }
       ],
       "description": "All possible responses that a client can send to an agent.\n\nThis enum is used internally for routing RPC responses. You typically won't need\nto use this directly - the responses are handled automatically by the connection.\n\nThese are responses to the corresponding AgentRequest variants.",
@@ -626,6 +634,19 @@
       "x-method": "initialize",
       "x-side": "agent"
     },
+    "KillTerminalRequest": {
+      "properties": {
+        "sessionId": {
+          "$ref": "#/$defs/SessionId"
+        },
+        "terminalId": {
+          "type": "string"
+        }
+      },
+      "required": ["sessionId", "terminalId"],
+      "type": "object",
+      "x-docs-ignore": true
+    },
     "LoadSessionRequest": {
       "description": "Request parameters for loading an existing session.\n\nOnly available if the agent supports the `loadSession` capability.\n\nSee protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)",
       "properties": {

typescript/acp.ts

@@ -210,6 +210,16 @@ export class TerminalHandle {
     );
   }
 
+  async kill(): Promise<void> {
+    return await this.#connection.sendRequest(
+      schema.CLIENT_METHODS.terminal_kill,
+      {
+        sessionId: this.#sessionId,
+        terminalId: this.id,
+      },
+    );
+  }
+
   async release(): Promise<void> {
     await this.#connection.sendRequest(schema.CLIENT_METHODS.terminal_release, {
       sessionId: this.#sessionId,
@@ -315,6 +325,13 @@ export class ClientSideConnection implements Agent {
             validatedParams as schema.WaitForTerminalExitRequest,
           );
         }
+        case schema.CLIENT_METHODS.terminal_kill: {
+          const validatedParams =
+            schema.killTerminalRequestSchema.parse(params);
+          return client.killTerminal?.(
+            validatedParams as schema.KillTerminalRequest,
+          );
+        }
         default:
           throw RequestError.methodNotFound(method);
       }
@@ -837,6 +854,13 @@ export interface Client {
   waitForTerminalExit?(
     params: schema.WaitForTerminalExitRequest,
   ): Promise<schema.WaitForTerminalExitResponse>;
+
+  /**
+   *  @internal **UNSTABLE**
+   *
+   * This method is not part of the spec, and may be removed or changed at any point.
+   */
+  killTerminal?(params: schema.KillTerminalRequest): Promise<void>;
 }
 
 /**

typescript/schema.ts

@@ -13,6 +13,7 @@ export const CLIENT_METHODS = {
   session_request_permission: "session/request_permission",
   session_update: "session/update",
   terminal_create: "terminal/create",
+  terminal_kill: "terminal/kill",
   terminal_output: "terminal/output",
   terminal_release: "terminal/release",
   terminal_wait_for_exit: "terminal/wait_for_exit",
@@ -45,7 +46,8 @@ export type ClientRequest =
   | CreateTerminalRequest
   | TerminalOutputRequest
   | ReleaseTerminalRequest
-  | WaitForTerminalExitRequest;
+  | WaitForTerminalExitRequest
+  | KillTerminalRequest;
 /**
  * Content produced by a tool call.
  *
@@ -197,9 +199,11 @@ export type ClientResponse =
   | CreateTerminalResponse
   | TerminalOutputResponse
   | ReleaseTerminalResponse
-  | WaitForTerminalExitResponse;
+  | WaitForTerminalExitResponse
+  | KillTerminalResponse;
 export type WriteTextFileResponse = null;
 export type ReleaseTerminalResponse = null;
+export type KillTerminalResponse = null;
 /**
  * All possible notifications that a client can send to an agent.
  *
@@ -496,6 +500,10 @@ export interface WaitForTerminalExitRequest {
   sessionId: SessionId;
   terminalId: string;
 }
+export interface KillTerminalRequest {
+  sessionId: SessionId;
+  terminalId: string;
+}
 /**
  * Response containing the contents of a text file.
  */
@@ -1084,6 +1092,9 @@ export const waitForTerminalExitResponseSchema = z.object({
   signal: z.string().optional().nullable(),
 });
 
+/** @internal */
+export const killTerminalResponseSchema = z.null();
+
 /** @internal */
 export const cancelNotificationSchema = z.object({
   sessionId: z.string(),
@@ -1223,6 +1234,12 @@ export const waitForTerminalExitRequestSchema = z.object({
   terminalId: z.string(),
 });
 
+/** @internal */
+export const killTerminalRequestSchema = z.object({
+  sessionId: sessionIdSchema,
+  terminalId: z.string(),
+});
+
 /** @internal */
 export const terminalExitStatusSchema = z.object({
   exitCode: z.number().optional().nullable(),
@@ -1441,6 +1458,7 @@ export const clientResponseSchema = z.union([
   terminalOutputResponseSchema,
   releaseTerminalResponseSchema,
   waitForTerminalExitResponseSchema,
+  killTerminalResponseSchema,
 ]);
 
 /** @internal */
@@ -1475,6 +1493,7 @@ export const clientRequestSchema = z.union([
   terminalOutputRequestSchema,
   releaseTerminalRequestSchema,
   waitForTerminalExitRequestSchema,
+  killTerminalRequestSchema,
 ]);
 
 /** @internal */