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

# ClientSideConnection

> Client-side connection to an agent in the ACP protocol

## Overview

A client-side connection to an agent. This class provides the client's view of an ACP connection, allowing clients (such as code editors) to communicate with agents. It implements the `Agent` interface to provide methods for initializing sessions, sending prompts, and managing the agent lifecycle.

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

## Constructor

```typescript theme={null}
constructor(
  toClient: (agent: Agent) => Client,
  stream: Stream
)
```

Creates a new client-side connection to an agent. This establishes the communication channel between a client and agent following the ACP specification.

<ParamField path="toClient" type="(agent: Agent) => Client" required>
  A function that creates a Client handler to process incoming agent 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

### initialize

```typescript theme={null}
async initialize(
  params: InitializeRequest
): Promise<InitializeResponse>
```

Establishes the connection with a client and negotiates protocol capabilities.

This method is called once at the beginning of the connection to:

* Negotiate the protocol version to use
* Exchange capability information between client and agent
* Determine available authentication methods

The agent should respond with its supported protocol version and capabilities.

<ParamField path="params" type="InitializeRequest" required>
  The initialization request parameters
</ParamField>

<ResponseField name="response" type="InitializeResponse">
  The agent's capabilities and protocol version
</ResponseField>

See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)

### newSession

```typescript theme={null}
async newSession(
  params: NewSessionRequest
): Promise<NewSessionResponse>
```

Creates a new conversation session with the agent.

Sessions represent independent conversation contexts with their own history and state.

The agent should:

* Create a new session context
* Connect to any specified MCP servers
* Return a unique session ID for future requests

May return an `auth_required` error if the agent requires authentication.

<ParamField path="params" type="NewSessionRequest" required>
  The new session request parameters
</ParamField>

<ResponseField name="response" type="NewSessionResponse">
  The new session information including session ID
</ResponseField>

See protocol docs: [Session Setup](https://agentclientprotocol.com/protocol/session-setup)

### loadSession

```typescript theme={null}
async loadSession(
  params: LoadSessionRequest
): Promise<LoadSessionResponse>
```

Loads an existing session to resume a previous conversation.

This method is only available if the agent advertises the `loadSession` capability.

The agent should:

* Restore the session context and conversation history
* Connect to the specified MCP servers
* Stream the entire conversation history back to the client via notifications

<ParamField path="params" type="LoadSessionRequest" required>
  The load session request parameters
</ParamField>

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

See protocol docs: [Loading Sessions](https://agentclientprotocol.com/protocol/session-setup#loading-sessions)

### unstable\_forkSession

```typescript theme={null}
async unstable_forkSession(
  params: ForkSessionRequest
): Promise<ForkSessionResponse>
```

**UNSTABLE** - This capability is not part of the spec yet, and may be removed or changed at any point.

Forks an existing session to create a new independent session.

Creates a new session based on the context of an existing one, allowing operations like generating summaries without affecting the original session's history.

This method is only available if the agent advertises the `session.fork` capability.

<ParamField path="params" type="ForkSessionRequest" required>
  The fork session request parameters
</ParamField>

<ResponseField name="response" type="ForkSessionResponse">
  The forked session information
</ResponseField>

### unstable\_listSessions

```typescript theme={null}
async unstable_listSessions(
  params: ListSessionsRequest
): Promise<ListSessionsResponse>
```

**UNSTABLE** - This capability is not part of the spec yet, and may be removed or changed at any point.

Lists existing sessions from the agent.

This method is only available if the agent advertises the `listSessions` capability.

Returns a list of sessions with metadata like session ID, working directory, title, and last update time. Supports filtering by working directory and cursor-based pagination.

<ParamField path="params" type="ListSessionsRequest" required>
  The list sessions request parameters
</ParamField>

<ResponseField name="response" type="ListSessionsResponse">
  The list of sessions with metadata
</ResponseField>

### unstable\_resumeSession

```typescript theme={null}
async unstable_resumeSession(
  params: ResumeSessionRequest
): Promise<ResumeSessionResponse>
```

**UNSTABLE** - This capability is not part of the spec yet, and may be removed or changed at any point.

Resumes an existing session without returning previous messages.

This method is only available if the agent advertises the `session.resume` capability.

The agent should resume the session context, allowing the conversation to continue without replaying the message history (unlike `session/load`).

<ParamField path="params" type="ResumeSessionRequest" required>
  The resume session request parameters
</ParamField>

<ResponseField name="response" type="ResumeSessionResponse">
  The resumed session information
</ResponseField>

### setSessionMode

```typescript theme={null}
async setSessionMode(
  params: SetSessionModeRequest
): Promise<SetSessionModeResponse>
```

Sets the operational mode for a session.

Allows switching between different agent modes (e.g., "ask", "architect", "code") that affect system prompts, tool availability, and permission behaviors.

The mode must be one of the modes advertised in `availableModes` during session creation or loading. Agents may also change modes autonomously and notify the client via `current_mode_update` notifications.

This method can be called at any time during a session, whether the Agent is idle or actively generating a turn.

<ParamField path="params" type="SetSessionModeRequest" required>
  The set session mode request parameters
</ParamField>

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

See protocol docs: [Session Modes](https://agentclientprotocol.com/protocol/session-modes)

### unstable\_setSessionModel

```typescript theme={null}
async unstable_setSessionModel(
  params: SetSessionModelRequest
): Promise<SetSessionModelResponse>
```

**UNSTABLE** - This capability is not part of the spec yet, and may be removed or changed at any point.

Select a model for a given session.

<ParamField path="params" type="SetSessionModelRequest" required>
  The set session model request parameters
</ParamField>

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

### setSessionConfigOption

```typescript theme={null}
async setSessionConfigOption(
  params: SetSessionConfigOptionRequest
): Promise<SetSessionConfigOptionResponse>
```

Set a configuration option for a given session.

The response contains the full set of configuration options and their current values, as changing one option may affect the available values or state of other options.

<ParamField path="params" type="SetSessionConfigOptionRequest" required>
  The set config option request parameters
</ParamField>

<ResponseField name="response" type="SetSessionConfigOptionResponse">
  The full set of configuration options and their current values
</ResponseField>

### authenticate

```typescript theme={null}
async authenticate(
  params: AuthenticateRequest
): Promise<AuthenticateResponse>
```

Authenticates the client using the specified authentication method.

Called when the agent requires authentication before allowing session creation. The client provides the authentication method ID that was advertised during initialization.

After successful authentication, the client can proceed to create sessions with `newSession` without receiving an `auth_required` error.

<ParamField path="params" type="AuthenticateRequest" required>
  The authentication request parameters
</ParamField>

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

See protocol docs: [Initialization](https://agentclientprotocol.com/protocol/initialization)

### prompt

```typescript theme={null}
async prompt(params: PromptRequest): Promise<PromptResponse>
```

Processes a user prompt within a session.

This method handles the whole lifecycle of a prompt:

* Receives user messages with optional context (files, images, etc.)
* Processes the prompt using language models
* Reports language model content and tool calls to the Clients
* Requests permission to run tools
* Executes any requested tool calls
* Returns when the turn is complete with a stop reason

<ParamField path="params" type="PromptRequest" required>
  The prompt request parameters
</ParamField>

<ResponseField name="response" type="PromptResponse">
  The prompt response with stop reason
</ResponseField>

See protocol docs: [Prompt Turn](https://agentclientprotocol.com/protocol/prompt-turn)

### cancel

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

Cancels ongoing operations for a session.

This is a notification sent by the client to cancel an ongoing prompt turn.

Upon receiving this notification, the Agent SHOULD:

* Stop all language model requests as soon as possible
* Abort all tool call invocations in progress
* Send any pending `session/update` notifications
* Respond to the original `session/prompt` request with `StopReason::Cancelled`

<ParamField path="params" type="CancelNotification" required>
  The cancellation notification parameters
</ParamField>

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

See protocol docs: [Cancellation](https://agentclientprotocol.com/protocol/prompt-turn#cancellation)

### extMethod

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

Extension method. Allows the Client 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 Client 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 ClientSideConnection(client, 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 ClientSideConnection(client, stream);
await connection.closed;
console.log('Connection closed - performing cleanup');
```