Add docs to ts library

Author: agu-z

docs/protocol/initialization.mdx

@@ -120,7 +120,8 @@ The Client **SHOULD** specify whether it supports the following capabilities:
 #### Terminal
 
 <ParamField path="terminal" type="boolean">
-  All `terminal/*` methods are available, allowing the Agent to execute and manage shell commands.
+  All `terminal/*` methods are available, allowing the Agent to execute and
+  manage shell commands.
 </ParamField>
 
 <Card icon="terminal" horizontal href="./terminals">

docs/protocol/schema.mdx

@@ -2124,9 +2124,11 @@ File modification shown as a diff.
 </ResponseField>
 
 <ResponseField name="terminal">
-Embed a terminal created with `terminal/create`
+Embed a terminal created with `terminal/create` by its id.
 
-The terminal must be added to the tool call before calling `terminal/release`.
+The terminal must be added before calling `terminal/release`.
+
+See protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminal)
 
 <Expandable title="Properties">
 

docs/protocol/terminals.mdx

@@ -64,20 +64,23 @@ The `terminal/create` method starts a command in a new terminal:
 <ParamField path="env" type="EnvVariable[]">
   Optional environment variables for the command.
 
-  Each variable has:
-  - `name`: The environment variable name
-  - `value`: The environment variable value
+Each variable has:
+
+- `name`: The environment variable name
+- `value`: The environment variable value
+
 </ParamField>
 
 <ParamField path="cwd" type="string">
   Optional working directory for the command (absolute path)
 </ParamField>
 
 <ParamField path="outputByteLimit" type="number">
-  Optional maximum number of output bytes to retain. Once exceeded, earlier output is truncated to stay within this limit.
+  Optional maximum number of output bytes to retain. Once exceeded, earlier
+  output is truncated to stay within this limit.
 </ParamField>
 
- The Client returns a Terminal ID immediately without waiting for completion:
+The Client returns a Terminal ID immediately without waiting for completion:
 
 ```json
 {
@@ -94,11 +97,10 @@ This allows the command to run in the background while the Agent performs other
 After creating the terminal, the Agent can use the `terminal/wait_for_exit` method to wait for the command to complete.
 
 <Note>
-The Agent **MUST** release the terminal using `terminal/release` when it's no longer needed.
+  The Agent **MUST** release the terminal using `terminal/release` when it's no
+  longer needed.
 </Note>
 
-
-
 ## Embedding in Tool Calls
 
 Terminals can be embedded directly in [tool calls](./tool-calls) to provide real-time output to users:
@@ -171,8 +173,10 @@ The Client responds with the current output and exit status (if the command has
 
 <ResponseField name="exitStatus" type="TerminalExitStatus">
   Present only if the command has exited. Contains:
-  - `exitCode`: The process exit code (may be null)
-  - `signal`: The signal that terminated the process (may be null)
+
+- `exitCode`: The process exit code (may be null)
+- `signal`: The signal that terminated the process (may be null)
+
 </ResponseField>
 
 ## Waiting for Exit
@@ -229,6 +233,7 @@ The `terminal/kill` method terminates a command without releasing the terminal:
 ```
 
 After killing a command, the terminal remains valid and can be used with:
+
 - `terminal/output` to get the final output
 - `terminal/wait_for_exit` to get the exit status
 

schema/schema.json

@@ -1742,7 +1742,7 @@
           "type": "object"
         },
         {
-          "description": "Embed a terminal created with `terminal/create`\n\nThe terminal must be added to the tool call before calling `terminal/release`.",
+          "description": "Embed a terminal created with `terminal/create` by its id.\n\nThe terminal must be added before calling `terminal/release`.\n\nSee protocol docs: [Terminal](https://agentclientprotocol.com/protocol/terminal)",
           "properties": {
             "terminalId": {
               "type": "string"

typescript/acp.ts

@@ -167,9 +167,16 @@ export class AgentSideConnection {
   }
 
   /**
-   *  @internal **UNSTABLE**
+   * Executes a command in a new terminal.
    *
-   * This method is not part of the spec, and may be removed or changed at any point.
+   * Returns a `TerminalHandle` that can be used to get output, wait for exit,
+   * kill the command, or release the terminal.
+   *
+   * The terminal can also be embedded in tool calls by using its ID in
+   * `ToolCallContent` with type "terminal".
+   *
+   * @param params - The terminal creation parameters
+   * @returns A handle to control and monitor the terminal
    */
   async createTerminal(
     params: schema.CreateTerminalRequest,
@@ -187,6 +194,22 @@ export class AgentSideConnection {
   }
 }
 
+/**
+ * Handle for controlling and monitoring a terminal created via `createTerminal`.
+ *
+ * Provides methods to:
+ * - Get current output without waiting
+ * - Wait for command completion
+ * - Kill the running command
+ * - Release terminal resources
+ *
+ * **Important:** Always call `release()` when done with the terminal to free resources.
+
+ * The terminal supports async disposal via `Symbol.asyncDispose` for automatic cleanup.
+
+ * You can use `await using` to ensure the terminal is automatically released when it
+ * goes out of scope.
+ */
 export class TerminalHandle {
   #sessionId: string;
   #connection: Connection;
@@ -200,6 +223,9 @@ export class TerminalHandle {
     this.#connection = conn;
   }
 
+  /**
+   * Gets the current terminal output without waiting for the command to exit.
+   */
   async currentOutput(): Promise<schema.TerminalOutputResponse> {
     return await this.#connection.sendRequest(
       schema.CLIENT_METHODS.terminal_output,
@@ -210,6 +236,9 @@ export class TerminalHandle {
     );
   }
 
+  /**
+   * Waits for the terminal command to complete and returns its exit status.
+   */
   async waitForExit(): Promise<schema.WaitForTerminalExitResponse> {
     return await this.#connection.sendRequest(
       schema.CLIENT_METHODS.terminal_wait_for_exit,
@@ -220,6 +249,16 @@ export class TerminalHandle {
     );
   }
 
+  /**
+   * Kills the terminal command without releasing the terminal.
+   *
+   * The terminal remains valid after killing, allowing you to:
+   * - Get the final output with `currentOutput()`
+   * - Check the exit status
+   * - Release the terminal when done
+   *
+   * Useful for implementing timeouts or cancellation.
+   */
   async kill(): Promise<void> {
     return await this.#connection.sendRequest(
       schema.CLIENT_METHODS.terminal_kill,
@@ -230,6 +269,18 @@ export class TerminalHandle {
     );
   }
 
+  /**
+   * Releases the terminal and frees all associated resources.
+   *
+   * If the command is still running, it will be killed.
+   * After release, the terminal ID becomes invalid and cannot be used
+   * with other terminal methods.
+   *
+   * Tool calls that already reference this terminal will continue to
+   * display its output.
+   *
+   * **Important:** Always call this method when done with the terminal.
+   */
   async release(): Promise<void> {
     await this.#connection.sendRequest(schema.CLIENT_METHODS.terminal_release, {
       sessionId: this.#sessionId,
@@ -851,43 +902,68 @@ export interface Client {
   ): Promise<schema.ReadTextFileResponse>;
 
   /**
-   *  @internal **UNSTABLE**
+   * Creates a new terminal to execute a command.
    *
-   * This method is not part of the spec, and may be removed or changed at any point.
+   * Only available if the `terminal` capability is set to `true`.
+   *
+   * The Agent must call `releaseTerminal` when done with the terminal
+   * to free resources.
+
+   * @see {@link https://agentclientprotocol.com/protocol/terminals | Terminal Documentation}
    */
   createTerminal?(
     params: schema.CreateTerminalRequest,
   ): Promise<schema.CreateTerminalResponse>;
 
   /**
-   *  @internal **UNSTABLE**
+   * Gets the current output and exit status of a terminal.
    *
-   * This method is not part of the spec, and may be removed or changed at any point.
+   * Returns immediately without waiting for the command to complete.
+   * If the command has already exited, the exit status is included.
+   *
+   * @see {@link https://agentclientprotocol.com/protocol/terminals#getting-output | Getting Terminal Output}
    */
   terminalOutput?(
     params: schema.TerminalOutputRequest,
   ): Promise<schema.TerminalOutputResponse>;
 
   /**
-   *  @internal **UNSTABLE**
+   * Releases a terminal and frees all associated resources.
    *
-   * This method is not part of the spec, and may be removed or changed at any point.
+   * The command is killed if it hasn't exited yet. After release,
+   * the terminal ID becomes invalid for all other terminal methods.
+   *
+   * Tool calls that already contain the terminal ID continue to
+   * display its output.
+   *
+   * @see {@link https://agentclientprotocol.com/protocol/terminals#releasing-terminals | Releasing Terminals}
    */
   releaseTerminal?(params: schema.ReleaseTerminalRequest): Promise<void>;
 
   /**
-   *  @internal **UNSTABLE**
+   * Waits for a terminal command to exit and returns its exit status.
    *
-   * This method is not part of the spec, and may be removed or changed at any point.
+   * This method returns once the command completes, providing the
+   * exit code and/or signal that terminated the process.
+   *
+   * @see {@link https://agentclientprotocol.com/protocol/terminals#waiting-for-exit | Waiting for Exit}
    */
   waitForTerminalExit?(
     params: schema.WaitForTerminalExitRequest,
   ): Promise<schema.WaitForTerminalExitResponse>;
 
   /**
-   *  @internal **UNSTABLE**
+   * Kills a terminal command without releasing the terminal.
    *
-   * This method is not part of the spec, and may be removed or changed at any point.
+   * While `releaseTerminal` also kills the command, this method keeps
+   * the terminal ID valid so it can be used with other methods.
+   *
+   * Useful for implementing command timeouts that terminate the command
+   * and then retrieve the final output.
+   *
+   * Note: Call `releaseTerminal` when the terminal is no longer needed.
+   *
+   * @see {@link https://agentclientprotocol.com/protocol/terminals#killing-commands | Killing Commands}
    */
   killTerminal?(params: schema.KillTerminalCommandRequest): Promise<void>;
 }