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
Constructor
constructor(
toClient: (agent: Agent) => Client,
stream: Stream
)
toClient
(agent: Agent) => Client
required
A function that creates a Client handler to process incoming agent requests
The bidirectional message stream for communication. Typically created using ndJsonStream for stdio-based connections.
Methods
initialize
async initialize(
params: InitializeRequest
): Promise<InitializeResponse>
- 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.
params
InitializeRequest
required
The initialization request parameters
The agent’s capabilities and protocol version
newSession
async newSession(
params: NewSessionRequest
): Promise<NewSessionResponse>
- 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.
params
NewSessionRequest
required
The new session request parameters
The new session information including session ID
loadSession
async loadSession(
params: LoadSessionRequest
): Promise<LoadSessionResponse>
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
params
LoadSessionRequest
required
The load session request parameters
An empty object on success
unstable_forkSession
async unstable_forkSession(
params: ForkSessionRequest
): Promise<ForkSessionResponse>
session.fork capability.
params
ForkSessionRequest
required
The fork session request parameters
The forked session information
unstable_listSessions
async unstable_listSessions(
params: ListSessionsRequest
): Promise<ListSessionsResponse>
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.
params
ListSessionsRequest
required
The list sessions request parameters
The list of sessions with metadata
unstable_resumeSession
async unstable_resumeSession(
params: ResumeSessionRequest
): Promise<ResumeSessionResponse>
session.resume capability.
The agent should resume the session context, allowing the conversation to continue without replaying the message history (unlike session/load).
params
ResumeSessionRequest
required
The resume session request parameters
The resumed session information
setSessionMode
async setSessionMode(
params: SetSessionModeRequest
): Promise<SetSessionModeResponse>
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.
params
SetSessionModeRequest
required
The set session mode request parameters
An empty object on success
unstable_setSessionModel
async unstable_setSessionModel(
params: SetSessionModelRequest
): Promise<SetSessionModelResponse>
params
SetSessionModelRequest
required
The set session model request parameters
An empty object on success
setSessionConfigOption
async setSessionConfigOption(
params: SetSessionConfigOptionRequest
): Promise<SetSessionConfigOptionResponse>
params
SetSessionConfigOptionRequest
required
The set config option request parameters
response
SetSessionConfigOptionResponse
The full set of configuration options and their current values
authenticate
async authenticate(
params: AuthenticateRequest
): Promise<AuthenticateResponse>
newSession without receiving an auth_required error.
params
AuthenticateRequest
required
The authentication request parameters
An empty object on success
prompt
async prompt(params: PromptRequest): Promise<PromptResponse>
- 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
The prompt request parameters
The prompt response with stop reason
cancel
async cancel(params: CancelNotification): Promise<void>
- 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
params
CancelNotification
required
The cancellation notification parameters
A promise that resolves when the notification has been sent
extMethod
async extMethod(
method: string,
params: Record<string, unknown>
): Promise<Record<string, unknown>>
The extension method name
params
Record<string, unknown>
required
The extension method parameters
The extension method response
extNotification
async extNotification(
method: string,
params: Record<string, unknown>
): Promise<void>
The extension notification name
params
Record<string, unknown>
required
The extension notification parameters
A promise that resolves when the notification has been sent
Properties
signal
get signal(): AbortSignal
- 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 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
get closed(): Promise<void>
const connection = new ClientSideConnection(client, stream);
await connection.closed;
console.log('Connection closed - performing cleanup');
