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

> The agent-side connection class for communicating with ACP clients

## Overview

The `AgentSideConnection` class provides the agent's view of an ACP connection, allowing agents to communicate with clients. It handles the bidirectional JSON-RPC communication and provides methods for sending session updates, requesting permissions, and accessing client capabilities.

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

## Constructor

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

<ParamField path="toAgent" type="function" required>
  A factory function that creates an Agent handler to process incoming client requests. The function receives the `AgentSideConnection` instance as a parameter.
</ParamField>

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

### Example

```typescript theme={null}
import * as acp from "@agentprotocol/acp";
import { Readable, Writable } from "node:stream";

class MyAgent implements acp.Agent {
  constructor(private connection: acp.AgentSideConnection) {}
  // ... implement Agent interface
}

const input = Writable.toWeb(process.stdout);
const output = Readable.toWeb(process.stdin);
const stream = acp.ndJsonStream(input, output);

const connection = new acp.AgentSideConnection(
  (conn) => new MyAgent(conn),
  stream
);
```

## Methods

### sessionUpdate

Sends session update notifications to the client.

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

<ParamField path="params" type="SessionNotification" required>
  The session update to send, containing the session ID and update content (message chunks, tool calls, etc.)
</ParamField>

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.
</Note>

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

### requestPermission

Requests permission from the user for a tool call operation.

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

<ParamField path="params" type="RequestPermissionRequest" required>
  The permission request containing the session ID, tool call details, and available options
</ParamField>

<ResponseField name="outcome" type="RequestPermissionOutcome" required>
  The user's decision, including the selected option ID or cancellation status
</ResponseField>

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

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

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

### readTextFile

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

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

<ParamField path="params.sessionId" type="string" required>
  The session ID making the request
</ParamField>

<ParamField path="params.path" type="string" required>
  Absolute path to the file to read
</ParamField>

<ResponseField name="content" type="string" required>
  The file contents as a string
</ResponseField>

<Note>
  Only available if the client advertises the `fs.readTextFile` capability during initialization.
</Note>

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

### writeTextFile

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

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

<ParamField path="params.sessionId" type="string" required>
  The session ID making the request
</ParamField>

<ParamField path="params.path" type="string" required>
  Absolute path to the file to write
</ParamField>

<ParamField path="params.content" type="string" required>
  The content to write to the file
</ParamField>

<Note>
  Only available if the client advertises the `fs.writeTextFile` capability during initialization.
</Note>

Allows the agent to create or modify files within the client's environment.

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

### createTerminal

Executes a command in a new terminal.

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

<ParamField path="params.sessionId" type="string" required>
  The session ID creating the terminal
</ParamField>

<ParamField path="params.command" type="string" required>
  The command to execute
</ParamField>

<ParamField path="params.args" type="string[]">
  Optional command arguments
</ParamField>

<ParamField path="params.workingDirectory" type="string">
  Optional working directory for the command
</ParamField>

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

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

### extMethod

Sends an arbitrary request that is not part of the ACP specification.

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

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

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

Allows the agent to send custom requests to the client.

### extNotification

Sends an arbitrary notification that is not part of the ACP specification.

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

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

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

Allows the agent to send custom notifications to the client.

## Properties

### signal

An `AbortSignal` that aborts when the connection closes.

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

This signal can be used to:

* Listen for connection closure
* Check connection status synchronously
* Pass to other APIs (fetch, setTimeout) for automatic cancellation

```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

A promise that resolves when the connection closes.

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

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.

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