First terminal methods

Author: agu-z

AGENTS.md

@@ -1,6 +1,19 @@
 All paths in the protocol should be absolute
 
-When updating JSON-RPC methods, their params, or output:
+When I ask you to add a new ACP Agent or Client method:
+
+- Create empty params and output structs in rust/client.rs or rust/agent.rs under the corresponding section. I'll add the fields myself.
+- 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 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`
+
+When updating existing JSON-RPC 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

@@ -70,7 +70,7 @@ See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/ini
 <ResponseField name="clientCapabilities" type={<a href="#clientcapabilities">ClientCapabilities</a>} >
   Capabilities supported by the client.
 
-    - Default: `{"fs":{"readTextFile":false,"writeTextFile":false}}`
+    - Default: `{"fs":{"readTextFile":false,"writeTextFile":false},"terminal":false}`
 
 </ResponseField>
 <ResponseField name="protocolVersion" type={<a href="#protocolversion">ProtocolVersion</a>} required>
@@ -517,6 +517,75 @@ See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protoc
   The actual update content.
 </ResponseField>
 
+<a id="terminal-new"></a>
+### <span class="font-mono">terminal/new</span>
+
+#### <span class="font-mono">NewTerminalRequest</span>
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>} >
+</ResponseField>
+<ResponseField name="command" type={"string"} required>
+</ResponseField>
+<ResponseField name="cwd" type={"string | null"} >
+</ResponseField>
+<ResponseField name="env" type={<><span><a href="#envvariable">EnvVariable</a></span><span>[]</span></>} >
+</ResponseField>
+<ResponseField name="outputByteLimit" type={"integer | null"} >
+
+    - Minimum: `0`
+
+</ResponseField>
+<ResponseField name="sessionId" type={<a href="#sessionid">SessionId</a>} required>
+</ResponseField>
+
+#### <span class="font-mono">NewTerminalResponse</span>
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="terminalId" type={"string"} required></ResponseField>
+
+<a id="terminal-output"></a>
+### <span class="font-mono">terminal/output</span>
+
+#### <span class="font-mono">TerminalOutputRequest</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">TerminalOutputResponse</span>
+
+**Type:** Object
+
+**Properties:**
+
+<ResponseField name="exitCode" type={"integer | null"} >
+
+    - Minimum: `0`
+
+</ResponseField>
+<ResponseField name="finished" type={"boolean"} required>
+</ResponseField>
+<ResponseField name="output" type={"string"} required>
+</ResponseField>
+<ResponseField name="signal" type={"string | null"} >
+</ResponseField>
+<ResponseField name="truncated" type={"boolean"} required>
+</ResponseField>
+
 ## <span class="font-mono">AgentCapabilities</span>
 
 Capabilities supported by the agent.
@@ -636,6 +705,11 @@ Determines which file operations the agent can request.
 
     - Default: `{"readTextFile":false,"writeTextFile":false}`
 
+</ResponseField>
+<ResponseField name="terminal" type={"boolean"} >
+
+    - Default: `false`
+
 </ResponseField>
 
 ## <span class="font-mono">ContentBlock</span>
@@ -1642,6 +1716,17 @@ File modification shown as a diff.
 </Expandable>
 </ResponseField>
 
+<ResponseField name="terminal">
+{""}
+
+<Expandable title="Properties">
+
+<ResponseField name="terminalId" type={"string"} required></ResponseField>
+<ResponseField name="type" type={"string"} required></ResponseField>
+
+</Expandable>
+</ResponseField>
+
 ## <span class="font-mono">ToolCallId</span>
 
 Unique identifier for a tool call within a session.

rust/acp.rs

@@ -245,6 +245,12 @@ impl Side for ClientSide {
             FS_READ_TEXT_FILE_METHOD_NAME => serde_json::from_str(params.get())
                 .map(AgentRequest::ReadTextFileRequest)
                 .map_err(Into::into),
+            TERMINAL_NEW_METHOD_NAME => serde_json::from_str(params.get())
+                .map(AgentRequest::NewTerminalRequest)
+                .map_err(Into::into),
+            TERMINAL_OUTPUT_METHOD_NAME => serde_json::from_str(params.get())
+                .map(AgentRequest::TerminalOutputRequest)
+                .map_err(Into::into),
             _ => Err(Error::method_not_found()),
         }
     }
@@ -279,6 +285,14 @@ impl<T: Client> MessageHandler<ClientSide> for T {
                 let response = self.read_text_file(args).await?;
                 Ok(ClientResponse::ReadTextFileResponse(response))
             }
+            AgentRequest::NewTerminalRequest(args) => {
+                let response = self.new_terminal(args).await?;
+                Ok(ClientResponse::NewTerminalResponse(response))
+            }
+            AgentRequest::TerminalOutputRequest(args) => {
+                let response = self.terminal_output(args).await?;
+                Ok(ClientResponse::TerminalOutputResponse(response))
+            }
         }
     }
 
@@ -383,6 +397,30 @@ impl Client for AgentSideConnection {
             .await
     }
 
+    async fn new_terminal(
+        &self,
+        arguments: NewTerminalRequest,
+    ) -> Result<NewTerminalResponse, Error> {
+        self.conn
+            .request(
+                TERMINAL_NEW_METHOD_NAME,
+                Some(AgentRequest::NewTerminalRequest(arguments)),
+            )
+            .await
+    }
+
+    async fn terminal_output(
+        &self,
+        arguments: TerminalOutputRequest,
+    ) -> Result<TerminalOutputResponse, Error> {
+        self.conn
+            .request(
+                TERMINAL_OUTPUT_METHOD_NAME,
+                Some(AgentRequest::TerminalOutputRequest(arguments)),
+            )
+            .await
+    }
+
     async fn session_notification(&self, notification: SessionNotification) -> Result<(), Error> {
         self.conn.notify(
             SESSION_UPDATE_NOTIFICATION,

rust/client.rs

@@ -9,7 +9,7 @@ use anyhow::Result;
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
-use crate::{ContentBlock, Error, Plan, SessionId, ToolCall, ToolCallUpdate};
+use crate::{ContentBlock, EnvVariable, Error, Plan, SessionId, ToolCall, ToolCallUpdate};
 
 /// Defines the interface that ACP-compliant clients must implement.
 ///
@@ -54,6 +54,16 @@ pub trait Client {
         args: ReadTextFileRequest,
     ) -> impl Future<Output = Result<ReadTextFileResponse, Error>>;
 
+    fn new_terminal(
+        &self,
+        args: NewTerminalRequest,
+    ) -> impl Future<Output = Result<NewTerminalResponse, Error>>;
+
+    fn terminal_output(
+        &self,
+        args: TerminalOutputRequest,
+    ) -> impl Future<Output = Result<TerminalOutputResponse, Error>>;
+
     /// Handles session update notifications from the agent.
     ///
     /// This is a notification endpoint (no response expected) that receives
@@ -244,6 +254,60 @@ pub struct ReadTextFileResponse {
     pub content: String,
 }
 
+// Terminals
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema, PartialEq, Eq, Hash)]
+#[serde(transparent)]
+pub struct TerminalId(pub Arc<str>);
+
+impl std::fmt::Display for TerminalId {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(f, "{}", self.0)
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[schemars(extend("x-side" = "client", "x-method" = "terminal/new"))]
+#[serde(rename_all = "camelCase")]
+pub struct NewTerminalRequest {
+    pub session_id: SessionId,
+    pub command: String,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub args: Vec<String>,
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub env: Vec<EnvVariable>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub cwd: Option<PathBuf>,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub output_byte_limit: Option<u64>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[schemars(extend("x-side" = "client", "x-method" = "terminal/new"))]
+#[serde(rename_all = "camelCase")]
+pub struct NewTerminalResponse {
+    pub terminal_id: TerminalId,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[schemars(extend("x-side" = "client", "x-method" = "terminal/output"))]
+#[serde(rename_all = "camelCase")]
+pub struct TerminalOutputRequest {
+    pub session_id: SessionId,
+    pub terminal_id: TerminalId,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[schemars(extend("x-side" = "client", "x-method" = "terminal/output"))]
+#[serde(rename_all = "camelCase")]
+pub struct TerminalOutputResponse {
+    pub output: String,
+    pub truncated: bool,
+    pub finished: bool,
+    pub exit_code: Option<u32>,
+    pub signal: Option<String>,
+}
+
 // Capabilities
 
 /// Capabilities supported by the client.
@@ -259,6 +323,8 @@ pub struct ClientCapabilities {
     /// Determines which file operations the agent can request.
     #[serde(default)]
     pub fs: FileSystemCapability,
+    #[serde(default)]
+    pub terminal: bool,
 }
 
 /// File system capabilities that a client may support.
@@ -290,6 +356,10 @@ pub struct ClientMethodNames {
     pub fs_write_text_file: &'static str,
     /// Method for reading text files.
     pub fs_read_text_file: &'static str,
+    /// Method for creating new terminals.
+    pub terminal_new: &'static str,
+    /// Method for getting terminals output.
+    pub terminal_output: &'static str,
 }
 
 /// Constant containing all client method names.
@@ -298,6 +368,8 @@ pub const CLIENT_METHOD_NAMES: ClientMethodNames = ClientMethodNames {
     session_request_permission: SESSION_REQUEST_PERMISSION_METHOD_NAME,
     fs_write_text_file: FS_WRITE_TEXT_FILE_METHOD_NAME,
     fs_read_text_file: FS_READ_TEXT_FILE_METHOD_NAME,
+    terminal_new: TERMINAL_NEW_METHOD_NAME,
+    terminal_output: TERMINAL_OUTPUT_METHOD_NAME,
 };
 
 /// Notification name for session updates.
@@ -308,6 +380,10 @@ pub(crate) const SESSION_REQUEST_PERMISSION_METHOD_NAME: &str = "session/request
 pub(crate) const FS_WRITE_TEXT_FILE_METHOD_NAME: &str = "fs/write_text_file";
 /// Method name for reading text files.
 pub(crate) const FS_READ_TEXT_FILE_METHOD_NAME: &str = "fs/read_text_file";
+/// Method name for creating a new terminal.
+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";
 
 /// All possible requests that an agent can send to a client.
 ///
@@ -322,6 +398,8 @@ pub enum AgentRequest {
     WriteTextFileRequest(WriteTextFileRequest),
     ReadTextFileRequest(ReadTextFileRequest),
     RequestPermissionRequest(RequestPermissionRequest),
+    NewTerminalRequest(NewTerminalRequest),
+    TerminalOutputRequest(TerminalOutputRequest),
 }
 
 /// All possible responses that a client can send to an agent.
@@ -337,6 +415,8 @@ pub enum ClientResponse {
     WriteTextFileResponse,
     ReadTextFileResponse(ReadTextFileResponse),
     RequestPermissionResponse(RequestPermissionResponse),
+    NewTerminalResponse(NewTerminalResponse),
+    TerminalOutputResponse(TerminalOutputResponse),
 }
 
 /// All possible notifications that an agent can send to a client.

rust/example_client.rs

@@ -40,6 +40,20 @@ impl acp::Client for ExampleClient {
         Err(acp::Error::method_not_found())
     }
 
+    async fn new_terminal(
+        &self,
+        _args: acp::NewTerminalRequest,
+    ) -> anyhow::Result<acp::NewTerminalResponse, acp::Error> {
+        Err(acp::Error::method_not_found())
+    }
+
+    async fn terminal_output(
+        &self,
+        _args: acp::TerminalOutputRequest,
+    ) -> anyhow::Result<acp::TerminalOutputResponse, acp::Error> {
+        Err(acp::Error::method_not_found())
+    }
+
     async fn session_notification(
         &self,
         args: acp::SessionNotification,

rust/markdown_generator.rs

@@ -644,6 +644,8 @@ impl SideDocs {
             "fs/write_text_file" => self.client_methods.get("write_text_file").unwrap(),
             "fs/read_text_file" => self.client_methods.get("read_text_file").unwrap(),
             "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(),
             _ => panic!("Introduced a method? Add it here :)"),
         }
     }

rust/rpc_tests.rs

@@ -67,6 +67,17 @@ impl Client for TestClient {
         self.session_notifications.lock().unwrap().push(args);
         Ok(())
     }
+
+    async fn new_terminal(&self, _args: NewTerminalRequest) -> Result<NewTerminalResponse, Error> {
+        unimplemented!()
+    }
+
+    async fn terminal_output(
+        &self,
+        _args: TerminalOutputRequest,
+    ) -> Result<TerminalOutputResponse, Error> {
+        unimplemented!()
+    }
 }
 
 #[derive(Clone)]