ClientSideConnection | Agent Client Protocol - v1.4.0
Agent Client Protocol - v1.4.0
    Preparing search index...

    Class ClientSideConnection

    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

    Prefer client, which registers typed handlers with a single context object and supports connectWith and session helpers.

    Implements

    Index
    constructor
    signal closed
    initialize newSession loadSession unstable_forkSession listSessions deleteSession resumeSession closeSession setSessionMode setSessionConfigOption authenticate unstable_listProviders unstable_setProvider unstable_disableProvider logout prompt cancel unstable_startNes unstable_suggestNes unstable_closeNes unstable_didOpenDocument unstable_didChangeDocument unstable_didCloseDocument unstable_didSaveDocument unstable_didFocusDocument unstable_acceptNes unstable_rejectNes request notify extMethod extNotification

    • Creates a new client-side connection to an agent.

      This establishes the communication channel between a client and agent following the ACP specification.

      Parameters

      • toClient: (agent: Agent) => Client

        A function that creates a Client handler to process incoming agent requests

      • stream: Stream

        The bidirectional message stream for communication. Typically created using ndJsonStream for stdio-based connections.

        See protocol docs: Communication Model

      Returns ClientSideConnection

      Prefer client({ name }).connectWith(stream, async (ctx) => ...).

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

      Returns AbortSignal

      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 });
    • 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:

      Returns Promise<void>

      const connection = new ClientSideConnection(client, stream);
      await connection.closed;
      console.log('Connection closed - performing cleanup');

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

      See protocol docs: Initialization

      Parameters

      Returns Promise<InitializeResponse>

    • 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

      The request may include additionalDirectories to expand the session's filesystem scope beyond cwd without changing the base for relative paths.

      May return an auth_required error if the agent requires authentication.

      See protocol docs: Session Setup

      Parameters

      Returns Promise<NewSessionResponse>

    • 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

      The request may include additionalDirectories to set the complete list of additional workspace roots for the loaded session.

      See protocol docs: Loading Sessions

      Parameters

      Returns Promise<LoadSessionResponse>

    • Experimental

      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.

      The request may include additionalDirectories to set the complete list of additional workspace roots for the forked session.

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

      Parameters

      Returns Promise<ForkSessionResponse>

    • 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, additionalDirectories, and cursor-based pagination.

      Parameters

      Returns Promise<ListSessionsResponse>

    • 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).

      The request may include additionalDirectories to set the complete list of additional workspace roots for the resumed session.

      Parameters

      Returns Promise<ResumeSessionResponse>

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

      See protocol docs: Session Modes

      Parameters

      Returns Promise<SetSessionModeResponse>

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

      See protocol docs: Initialization

      Parameters

      Returns Promise<AuthenticateResponse>

    • 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

      See protocol docs: Prompt Turn

      Parameters

      Returns Promise<PromptResponse>

    • 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

      See protocol docs: Cancellation

      Parameters

      Returns Promise<void>

    • Extension method.

      Parameters

      • method: string
      • params: Record<string, unknown>

      Returns Promise<Record<string, unknown>>

      Use request.

    • Extension notification.

      Parameters

      • method: string
      • params: Record<string, unknown>

      Returns Promise<void>

      Use notify.

    Settings
    Member Visibility

    On This Page
    Constructors
    Accessors
    Methods