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
Constructor
constructor(
toAgent: (conn: AgentSideConnection) => Agent,
stream: Stream
)
A factory function that creates an Agent handler to process incoming client requests. The function receives the AgentSideConnection instance as a parameter.
The bidirectional message stream for communication. Typically created using ndJsonStream() for stdio-based connections.
Example
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.
async sessionUpdate(params: SessionNotification): Promise<void>
params
SessionNotification
required
The session update to send, containing the session ID and update content (message chunks, tool calls, etc.)
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.
requestPermission
Requests permission from the user for a tool call operation.
async requestPermission(
params: RequestPermissionRequest
): Promise<RequestPermissionResponse>
params
RequestPermissionRequest
required
The permission request containing the session ID, tool call details, and available options
outcome
RequestPermissionOutcome
required
The user’s decision, including the selected option ID or cancellation status
If the client cancels the prompt turn via session/cancel, it MUST respond to this request with RequestPermissionOutcome::Cancelled.
readTextFile
Reads content from a text file in the client’s file system.
async readTextFile(
params: ReadTextFileRequest
): Promise<ReadTextFileResponse>
The session ID making the request
Absolute path to the file to read
The file contents as a string
Only available if the client advertises the fs.readTextFile capability during initialization.
writeTextFile
Writes content to a text file in the client’s file system.
async writeTextFile(
params: WriteTextFileRequest
): Promise<WriteTextFileResponse>
The session ID making the request
Absolute path to the file to write
The content to write to the file
Only available if the client advertises the fs.writeTextFile capability during initialization.
createTerminal
Executes a command in a new terminal.
async createTerminal(
params: CreateTerminalRequest
): Promise<TerminalHandle>
The session ID creating the terminal
Optional command arguments
Optional working directory for the command
A handle to control and monitor the terminal
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.
async extMethod(
method: string,
params: Record<string, unknown>
): Promise<Record<string, unknown>>
The extension method name
params
Record<string, unknown>
required
The method parameters
extNotification
Sends an arbitrary notification that is not part of the ACP specification.
async extNotification(
method: string,
params: Record<string, unknown>
): Promise<void>
The extension notification name
params
Record<string, unknown>
required
The notification parameters
Properties
signal
An AbortSignal that aborts when the connection closes.
get signal(): AbortSignal
- Listen for connection closure
- Check connection status synchronously
- Pass to other APIs (fetch, setTimeout) for automatic cancellation
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.
get closed(): Promise<void>
const connection = new AgentSideConnection(agent, stream);
await connection.closed;
console.log('Connection closed - performing cleanup');
