> ## 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.

# AgentSideConnection

> Agent-side connection to a client in the ACP protocol

## Overview

An agent-side connection to a client. This class provides the agent's view of an ACP connection, allowing agents to communicate with clients. It implements the `Client` interface to provide methods for requesting permissions, accessing the file system, and sending session updates.

See protocol docs: [Agent](https://agentclientprotocol.com/protocol/overview#agent)

## Constructor

```typescript theme={null}
constructor(
  toAgent: (conn: AgentSideConnection) => Agent,
  stream: Stream
)
```

Creates a new agent-side connection to a client. This establishes the communication channel from the agent's perspective following the ACP specification.

<ParamField path="toAgent" type="(conn: AgentSideConnection) => Agent" required>
  A function that creates an Agent handler to process incoming client requests
</ParamField>

<ParamField path="stream" type="Stream" required>
  The bidirectional message stream for communication. Typically created using `ndJsonStream` for stdio-based connections.
</ParamField>

See protocol docs: [Communication Model](https://agentclientprotocol.com/protocol/overview#communication-model)

## Methods

### sessionUpdate

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

Handles session update notifications from the agent. This is a notification endpoint (no response expected) that sends 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 sent
</ResponseField>

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

### requestPermission

```typescript theme={null}
async 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)

### readTextFile

```typescript theme={null}
async 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)

### writeTextFile

```typescript theme={null}
async 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)

### createTerminal

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

Executes a command in a new terminal. 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".

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

<ResponseField name="handle" type="TerminalHandle">
  A handle to control and monitor the terminal
</ResponseField>

### extMethod

```typescript theme={null}
async 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.

<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}
async 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 sent
</ResponseField>

## Properties

### signal

```typescript theme={null}
get signal(): AbortSignal
```

AbortSignal that aborts when the connection closes.

This signal can be used to:

* Listen for connection closure: `connection.signal.addEventListener('abort', () => {...})`
* Check connection status synchronously: `if (connection.signal.aborted) {...}`
* Pass to other APIs (fetch, setTimeout) for automatic cancellation

The connection closes when the underlying stream ends, either normally or due to an error.

**Example:**

```typescript theme={null}
const connection = new AgentSideConnection(agent, stream);

// Listen for closure
connection.signal.addEventListener('abort', () => {
  console.log('Connection closed - performing cleanup');
});

// Check status
if (connection.signal.aborted) {
  console.log('Connection is already closed');
}

// Pass to other APIs
fetch(url, { signal: connection.signal });
```

### closed

```typescript theme={null}
get closed(): Promise<void>
```

Promise that resolves when the connection closes.

The connection closes when the underlying stream ends, either normally or due to an error. Once closed, the connection cannot send or receive any more messages.

This is useful for async/await style cleanup:

**Example:**

```typescript theme={null}
const connection = new AgentSideConnection(agent, stream);
await connection.closed;
console.log('Connection closed - performing cleanup');
```