Skip to main content

​
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

​
Constructor

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.
​
toAgent
(conn: AgentSideConnection) => Agent
required
A function that creates an Agent handler to process incoming client requests
​
stream
Stream
required
The bidirectional message stream for communication. Typically created using ndJsonStream for stdio-based connections.
See protocol docs: Communication Model

​
Methods

​
sessionUpdate

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.
​
params
SessionNotification
required
The session notification parameters containing updates about session progress
​
Promise<void>
Promise<void>
A promise that resolves when the notification has been sent
See protocol docs: Agent Reports Output

​
requestPermission

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.
​
params
RequestPermissionRequest
required
The permission request parameters
​
response
RequestPermissionResponse
The user’s permission decision
See protocol docs: Requesting Permission

​
readTextFile

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.
​
params
ReadTextFileRequest
required
The file read request parameters
​
response
ReadTextFileResponse
The file contents
See protocol docs: Client

​
writeTextFile

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.
​
params
WriteTextFileRequest
required
The file write request parameters
​
response
WriteTextFileResponse
An empty object on success
See protocol docs: Client

​
createTerminal

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”.
​
params
CreateTerminalRequest
required
The terminal creation parameters
​
handle
TerminalHandle
A handle to control and monitor the terminal

​
extMethod

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.
​
method
string
required
The extension method name
​
params
Record<string, unknown>
required
The extension method parameters
​
response
Record<string, unknown>
The extension method response

​
extNotification

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.
​
method
string
required
The extension notification name
​
params
Record<string, unknown>
required
The extension notification parameters
​
Promise<void>
Promise<void>
A promise that resolves when the notification has been sent

​
Properties

​
signal

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

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: 
const connection = new AgentSideConnection(agent, stream);
await connection.closed;
console.log('Connection closed - performing cleanup');

Build docs developers (and LLMs) love

Get started for freeTalk to us