> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentclientprotocol/typescript-sdk/llms.txt
> Use this file to discover all available pages before exploring further.

# Client Interface

> Interface that ACP-compliant clients must implement

## Overview

The Client interface defines the interface that ACP-compliant clients must implement.

Clients are typically code editors (IDEs, text editors) that provide the interface between users and AI agents. They manage the environment, handle user interactions, and control access to resources.

## Type Definition

```typescript theme={null}
export interface Client {
  // Required methods
  requestPermission(
    params: RequestPermissionRequest
  ): Promise<RequestPermissionResponse>;
  sessionUpdate(params: SessionNotification): Promise<void>;
  
  // Optional methods
  writeTextFile?(params: WriteTextFileRequest): Promise<WriteTextFileResponse>;
  readTextFile?(params: ReadTextFileRequest): Promise<ReadTextFileResponse>;
  createTerminal?(params: CreateTerminalRequest): Promise<CreateTerminalResponse>;
  terminalOutput?(params: TerminalOutputRequest): Promise<TerminalOutputResponse>;
  releaseTerminal?(params: ReleaseTerminalRequest): Promise<ReleaseTerminalResponse | void>;
  waitForTerminalExit?(params: WaitForTerminalExitRequest): Promise<WaitForTerminalExitResponse>;
  killTerminal?(params: KillTerminalRequest): Promise<KillTerminalResponse | void>;
  extMethod?(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;
  extNotification?(method: string, params: Record<string, unknown>): Promise<void>;
}
```

## Required Methods

### requestPermission

```typescript theme={null}
requestPermission(
  params: RequestPermissionRequest
): Promise<RequestPermissionResponse>
```

Requests permission from the user for a tool call operation.

Called by the agent when it needs user authorization before executing a potentially sensitive operation. The client should present the options to the user and return their decision.

If the client cancels the prompt turn via `session/cancel`, it MUST respond to this request with `RequestPermissionOutcome::Cancelled`.

<ParamField path="params" type="RequestPermissionRequest" required>
  The permission request parameters
</ParamField>

<ResponseField name="response" type="RequestPermissionResponse">
  The user's permission decision
</ResponseField>

See protocol docs: [Requesting Permission](https://agentclientprotocol.com/protocol/tool-calls#requesting-permission)

### sessionUpdate

```typescript theme={null}
sessionUpdate(params: SessionNotification): Promise<void>
```

Handles session update notifications from the agent.

This is a notification endpoint (no response expected) that receives real-time updates about session progress, including message chunks, tool calls, and execution plans.

Note: Clients SHOULD continue accepting tool call updates even after sending a `session/cancel` notification, as the agent may send final updates before responding with the cancelled stop reason.

<ParamField path="params" type="SessionNotification" required>
  The session notification parameters containing updates about session progress
</ParamField>

<ResponseField name="Promise<void>" type="Promise<void>">
  A promise that resolves when the notification has been processed
</ResponseField>

See protocol docs: [Agent Reports Output](https://agentclientprotocol.com/protocol/prompt-turn#3-agent-reports-output)

## Optional Methods

### writeTextFile

```typescript theme={null}
writeTextFile?(params: WriteTextFileRequest): Promise<WriteTextFileResponse>
```

Writes content to a text file in the client's file system.

Only available if the client advertises the `fs.writeTextFile` capability. Allows the agent to create or modify files within the client's environment.

<ParamField path="params" type="WriteTextFileRequest" required>
  The file write request parameters
</ParamField>

<ResponseField name="response" type="WriteTextFileResponse">
  An empty object on success
</ResponseField>

See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)

### readTextFile

```typescript theme={null}
readTextFile?(params: ReadTextFileRequest): Promise<ReadTextFileResponse>
```

Reads content from a text file in the client's file system.

Only available if the client advertises the `fs.readTextFile` capability. Allows the agent to access file contents within the client's environment.

<ParamField path="params" type="ReadTextFileRequest" required>
  The file read request parameters
</ParamField>

<ResponseField name="response" type="ReadTextFileResponse">
  The file contents
</ResponseField>

See protocol docs: [Client](https://agentclientprotocol.com/protocol/overview#client)

### createTerminal

```typescript theme={null}
createTerminal?(params: CreateTerminalRequest): Promise<CreateTerminalResponse>
```

Creates a new terminal to execute a command.

Only available if the `terminal` capability is set to `true`.

The Agent must call `releaseTerminal` when done with the terminal to free resources.

<ParamField path="params" type="CreateTerminalRequest" required>
  The terminal creation parameters
</ParamField>

<ResponseField name="response" type="CreateTerminalResponse">
  The terminal ID
</ResponseField>

See [Terminal Documentation](https://agentclientprotocol.com/protocol/terminals)

### terminalOutput

```typescript theme={null}
terminalOutput?(params: TerminalOutputRequest): Promise<TerminalOutputResponse>
```

Gets the current output and exit status of a terminal.

Returns immediately without waiting for the command to complete. If the command has already exited, the exit status is included.

<ParamField path="params" type="TerminalOutputRequest" required>
  The terminal output request parameters
</ParamField>

<ResponseField name="response" type="TerminalOutputResponse">
  The current terminal output and exit status (if available)
</ResponseField>

See [Getting Terminal Output](https://agentclientprotocol.com/protocol/terminals#getting-output)

### releaseTerminal

```typescript theme={null}
releaseTerminal?(params: ReleaseTerminalRequest): Promise<ReleaseTerminalResponse | void>
```

Releases a terminal and frees all associated resources.

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.

<ParamField path="params" type="ReleaseTerminalRequest" required>
  The release terminal request parameters
</ParamField>

<ResponseField name="response" type="ReleaseTerminalResponse | void">
  An empty object on success, or void
</ResponseField>

See [Releasing Terminals](https://agentclientprotocol.com/protocol/terminals#releasing-terminals)

### waitForTerminalExit

```typescript theme={null}
waitForTerminalExit?(params: WaitForTerminalExitRequest): Promise<WaitForTerminalExitResponse>
```

Waits for a terminal command to exit and returns its exit status.

This method returns once the command completes, providing the exit code and/or signal that terminated the process.

<ParamField path="params" type="WaitForTerminalExitRequest" required>
  The wait for exit request parameters
</ParamField>

<ResponseField name="response" type="WaitForTerminalExitResponse">
  The exit status of the terminal command
</ResponseField>

See [Waiting for Exit](https://agentclientprotocol.com/protocol/terminals#waiting-for-exit)

### killTerminal

```typescript theme={null}
killTerminal?(params: KillTerminalRequest): Promise<KillTerminalResponse | void>
```

Kills a terminal command without releasing the terminal.

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.

<ParamField path="params" type="KillTerminalRequest" required>
  The kill terminal request parameters
</ParamField>

<ResponseField name="response" type="KillTerminalResponse | void">
  An empty object on success, or void
</ResponseField>

See [Killing Commands](https://agentclientprotocol.com/protocol/terminals#killing-commands)

### extMethod

```typescript theme={null}
extMethod?(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>
```

Extension method. Allows the Agent to send an arbitrary request that is not part of the ACP spec.

To help avoid conflicts, it's a good practice to prefix extension methods with a unique identifier such as domain name.

<ParamField path="method" type="string" required>
  The extension method name
</ParamField>

<ParamField path="params" type="Record<string, unknown>" required>
  The extension method parameters
</ParamField>

<ResponseField name="response" type="Record<string, unknown>">
  The extension method response
</ResponseField>

### extNotification

```typescript theme={null}
extNotification?(method: string, params: Record<string, unknown>): Promise<void>
```

Extension notification. Allows the Agent to send an arbitrary notification that is not part of the ACP spec.

<ParamField path="method" type="string" required>
  The extension notification name
</ParamField>

<ParamField path="params" type="Record<string, unknown>" required>
  The extension notification parameters
</ParamField>

<ResponseField name="Promise<void>" type="Promise<void>">
  A promise that resolves when the notification has been processed
</ResponseField>