Release terminals

Author: agu-z

AGENTS.md

@@ -1,19 +1,35 @@
 All paths in the protocol should be absolute
 
-When I ask you to add a new ACP Agent or Client method:
+## Adding new methods
 
 - Create empty params and output structs in rust/client.rs or rust/agent.rs under the corresponding section. I'll add the fields myself.
+- If the protocol method name is `noun/verb`, use `verb_noun` for the user facing methods and structs.
+
+  Example 1 (`noun/noun`):
+  Protocol method: `terminal/output`
+  Trait method name: `terminal_output`
+  Request/Response structs: `TerminalOutputRequest` / `TerminalOutputResponse`
+  Method names struct: `terminal_output: &'static str`
+
+  Example 2 (`noun/verb`):
+  Protocol method: `terminal/new`
+  Trait method name: `new_terminal`
+  Request/Response structs: `NewTerminalRequest` / `NewTerminalResponse`
+  Method names struct: `terminal_new: &'static str`
+
 - Do not write any tests or docs at all!
 - 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 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
 - Add the method to typescript/acp.ts classes and handlers
 - Run `npm run check`
+- Update the example agents and clients in tests and examples in both libraries
 
-When updating existing JSON-RPC methods, their params, or output:
+## Updating existing methods, their params, or output
 
 - Update the mintlify docs and guides in the `docs` directory
 - Run `npm run check` to make sure the json and zod schemas gets generated properly

docs/protocol/schema.mdx

@@ -586,6 +586,22 @@ See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protoc
 <ResponseField name="truncated" type={"boolean"} required>
 </ResponseField>
 
+<a id="terminal-release"></a>
+### <span class="font-mono">terminal/release</span>
+
+#### <span class="font-mono">ReleaseTerminalRequest</span>
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField
+  name="sessionId"
+  type={<a href="#sessionid">SessionId</a>}
+  required
+></ResponseField>
+<ResponseField name="terminalId" type={"string"} required></ResponseField>
+
 ## <span class="font-mono">AgentCapabilities</span>
 
 Capabilities supported by the agent.

rust/acp.rs

@@ -251,6 +251,9 @@ impl Side for ClientSide {
             TERMINAL_OUTPUT_METHOD_NAME => serde_json::from_str(params.get())
                 .map(AgentRequest::TerminalOutputRequest)
                 .map_err(Into::into),
+            TERMINAL_RELEASE_METHOD_NAME => serde_json::from_str(params.get())
+                .map(AgentRequest::ReleaseTerminalRequest)
+                .map_err(Into::into),
             _ => Err(Error::method_not_found()),
         }
     }
@@ -293,6 +296,10 @@ impl<T: Client> MessageHandler<ClientSide> for T {
                 let response = self.terminal_output(args).await?;
                 Ok(ClientResponse::TerminalOutputResponse(response))
             }
+            AgentRequest::ReleaseTerminalRequest(args) => {
+                self.release_terminal(args).await?;
+                Ok(ClientResponse::ReleaseTerminalResponse)
+            }
         }
     }
 
@@ -421,6 +428,15 @@ impl Client for AgentSideConnection {
             .await
     }
 
+    async fn release_terminal(&self, arguments: ReleaseTerminalRequest) -> Result<(), Error> {
+        self.conn
+            .request(
+                TERMINAL_RELEASE_METHOD_NAME,
+                Some(AgentRequest::ReleaseTerminalRequest(arguments)),
+            )
+            .await
+    }
+
     async fn session_notification(&self, notification: SessionNotification) -> Result<(), Error> {
         self.conn.notify(
             SESSION_UPDATE_NOTIFICATION,

rust/client.rs

@@ -64,6 +64,11 @@ pub trait Client {
         args: TerminalOutputRequest,
     ) -> impl Future<Output = Result<TerminalOutputResponse, Error>>;
 
+    fn release_terminal(
+        &self,
+        args: ReleaseTerminalRequest,
+    ) -> impl Future<Output = Result<(), Error>>;
+
     /// Handles session update notifications from the agent.
     ///
     /// This is a notification endpoint (no response expected) that receives
@@ -308,6 +313,14 @@ pub struct TerminalOutputResponse {
     pub signal: Option<String>,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[schemars(extend("x-side" = "client", "x-method" = "terminal/release"))]
+#[serde(rename_all = "camelCase")]
+pub struct ReleaseTerminalRequest {
+    pub session_id: SessionId,
+    pub terminal_id: TerminalId,
+}
+
 // Capabilities
 
 /// Capabilities supported by the client.
@@ -360,6 +373,8 @@ pub struct ClientMethodNames {
     pub terminal_new: &'static str,
     /// Method for getting terminals output.
     pub terminal_output: &'static str,
+    /// Method for releasing terminals.
+    pub terminal_release: &'static str,
 }
 
 /// Constant containing all client method names.
@@ -370,6 +385,7 @@ pub const CLIENT_METHOD_NAMES: ClientMethodNames = ClientMethodNames {
     fs_read_text_file: FS_READ_TEXT_FILE_METHOD_NAME,
     terminal_new: TERMINAL_NEW_METHOD_NAME,
     terminal_output: TERMINAL_OUTPUT_METHOD_NAME,
+    terminal_release: TERMINAL_RELEASE_METHOD_NAME,
 };
 
 /// Notification name for session updates.
@@ -384,6 +400,8 @@ pub(crate) const FS_READ_TEXT_FILE_METHOD_NAME: &str = "fs/read_text_file";
 pub(crate) const TERMINAL_NEW_METHOD_NAME: &str = "terminal/new";
 /// Method for getting terminals output.
 pub(crate) const TERMINAL_OUTPUT_METHOD_NAME: &str = "terminal/output";
+/// Method for releasing a terminal.
+pub(crate) const TERMINAL_RELEASE_METHOD_NAME: &str = "terminal/release";
 
 /// All possible requests that an agent can send to a client.
 ///
@@ -400,6 +418,7 @@ pub enum AgentRequest {
     RequestPermissionRequest(RequestPermissionRequest),
     NewTerminalRequest(NewTerminalRequest),
     TerminalOutputRequest(TerminalOutputRequest),
+    ReleaseTerminalRequest(ReleaseTerminalRequest),
 }
 
 /// All possible responses that a client can send to an agent.
@@ -417,6 +436,7 @@ pub enum ClientResponse {
     RequestPermissionResponse(RequestPermissionResponse),
     NewTerminalResponse(NewTerminalResponse),
     TerminalOutputResponse(TerminalOutputResponse),
+    ReleaseTerminalResponse,
 }
 
 /// All possible notifications that an agent can send to a client.

rust/example_client.rs

@@ -54,6 +54,13 @@ impl acp::Client for ExampleClient {
         Err(acp::Error::method_not_found())
     }
 
+    async fn release_terminal(
+        &self,
+        _args: acp::ReleaseTerminalRequest,
+    ) -> anyhow::Result<(), acp::Error> {
+        Err(acp::Error::method_not_found())
+    }
+
     async fn session_notification(
         &self,
         args: acp::SessionNotification,

rust/markdown_generator.rs

@@ -646,6 +646,7 @@ impl SideDocs {
             "session/update" => self.client_methods.get("session_notification").unwrap(),
             "terminal/new" => self.client_methods.get("new_terminal").unwrap(),
             "terminal/output" => self.client_methods.get("terminal_output").unwrap(),
+            "terminal/release" => self.client_methods.get("release_terminal").unwrap(),
             _ => panic!("Introduced a method? Add it here :)"),
         }
     }

rust/rpc_tests.rs

@@ -78,6 +78,10 @@ impl Client for TestClient {
     ) -> Result<TerminalOutputResponse, Error> {
         unimplemented!()
     }
+
+    async fn release_terminal(&self, _args: ReleaseTerminalRequest) -> Result<(), Error> {
+        unimplemented!()
+    }
 }
 
 #[derive(Clone)]

schema/meta.json

@@ -13,7 +13,8 @@
     "session_request_permission": "session/request_permission",
     "session_update": "session/update",
     "terminal_new": "terminal/new",
-    "terminal_output": "terminal/output"
+    "terminal_output": "terminal/output",
+    "terminal_release": "terminal/release"
   },
   "version": 1
 }

schema/schema.json

@@ -51,6 +51,10 @@
         {
           "$ref": "#/$defs/TerminalOutputRequest",
           "title": "TerminalOutputRequest"
+        },
+        {
+          "$ref": "#/$defs/ReleaseTerminalRequest",
+          "title": "ReleaseTerminalRequest"
         }
       ],
       "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.",
@@ -264,6 +268,10 @@
         {
           "$ref": "#/$defs/TerminalOutputResponse",
           "title": "TerminalOutputResponse"
+        },
+        {
+          "title": "ReleaseTerminalResponse",
+          "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.",
@@ -918,6 +926,20 @@
       "required": ["content"],
       "type": "object"
     },
+    "ReleaseTerminalRequest": {
+      "properties": {
+        "sessionId": {
+          "$ref": "#/$defs/SessionId"
+        },
+        "terminalId": {
+          "type": "string"
+        }
+      },
+      "required": ["sessionId", "terminalId"],
+      "type": "object",
+      "x-method": "terminal/release",
+      "x-side": "client"
+    },
     "RequestPermissionOutcome": {
       "description": "The outcome of a permission request.",
       "oneOf": [

typescript/acp.ts

@@ -173,6 +173,13 @@ export class AgentSideConnection implements Client {
     );
   }
 
+  async releaseTerminal(params: schema.ReleaseTerminalRequest): Promise<void> {
+    return await this.#connection.sendRequest(
+      schema.CLIENT_METHODS.terminal_release,
+      params,
+    );
+  }
+
   /**
    * Writes content to a text file in the client's file system.
    *
@@ -269,6 +276,13 @@ export class ClientSideConnection implements Agent {
             validatedParams as schema.TerminalOutputRequest,
           );
         }
+        case schema.CLIENT_METHODS.terminal_release: {
+          const validatedParams =
+            schema.releaseTerminalRequestSchema.parse(params);
+          return client.releaseTerminal(
+            validatedParams as schema.ReleaseTerminalRequest,
+          );
+        }
         default:
           throw RequestError.methodNotFound(method);
       }
@@ -771,6 +785,7 @@ export interface Client {
   terminalOutput(
     params: schema.TerminalOutputRequest,
   ): Promise<schema.TerminalOutputResponse>;
+  releaseTerminal(params: schema.ReleaseTerminalRequest): Promise<void>;
 }
 
 /**