Creates a new ACP connection over the given Axon channel and devbox.
The constructor does not open an SSE subscription. Call connect to open the transport, then initialize to negotiate protocol capabilities.
The Axon channel to communicate over (from @runloop/api-client).
The Runloop devbox hosting the ACP agent.
Optionaloptions: ACPAxonConnectionOptionsOptional configuration for error handling, permissions, and lifecycle hooks.
ReadonlyaxonThe Axon channel ID this connection is bound to.
ReadonlydevboxThe Runloop devbox ID.
Promise that resolves when the connection closes.
A promise that settles once the protocol connection is fully closed.
The underlying ACP SDK ClientSideConnection.
Use this for direct access to experimental/unstable protocol methods
(e.g. unstable_forkSession, unstable_closeSession). For stable
methods, prefer the proxied methods on this class directly.
Only available after connect has been called.
AbortSignal that fires when the connection closes.
The underlying protocol's abort signal.
Aborts the underlying SSE stream without clearing registered listeners.
Unlike disconnect, this does not run ACPAxonConnectionOptions.onDisconnect and does not reset connect state. Prefer disconnect followed by connect for a full teardown and reconnect on the same instance.
Authenticates using a method advertised during initialization.
Authentication method and credentials.
The authentication result.
Cancels an ongoing prompt turn for a session.
Identifies the session whose turn should be cancelled.
Opens the Axon SSE subscription and creates the underlying
ClientSideConnection. Must be called before initialize.
When replay is true (the default), queries the axon for the
current head sequence and replays all events up to that point
without invoking handlers. Unresolved permission requests are
dispatched to handlers after replay completes.
Aborts the Axon stream, resets protocol state so connect can be
called again, and runs the onDisconnect callback (e.g. devbox teardown)
if one was provided.
User-registered listeners (onSessionUpdate, onAxonEvent, onTimelineEvent) are preserved across disconnect/reconnect.
Resolves once the onDisconnect callback (if any) completes.
Sends an arbitrary extension request not part of the ACP spec.
The custom method name.
Arbitrary key-value payload for the request.
The agent's response payload.
Sends an arbitrary extension notification not part of the ACP spec. Unlike extMethod, notifications do not expect a response.
The custom method name.
Arbitrary key-value payload for the notification.
Runs the ACP initialize protocol step (capability negotiation with the agent).
This is required once after connect on first startup of the agent session:
the transport is already open after connect(), but the ACP wire protocol expects
initialize before newSession, prompt, or other agent methods.
Protocol version, client info, and capability negotiation fields.
The agent's supported capabilities and protocol version.
Lists existing sessions from the agent.
Optional filter criteria for the session list.
An array of session summaries.
Loads an existing session to resume a previous conversation.
Identifies the session to load.
The restored session metadata.
Creates a new conversation session with the agent.
Session configuration including working directory and MCP servers.
The newly created session ID and metadata.
Registers a listener for every Axon event (before JSON-RPC translation). Useful for debugging, observability, and building event viewers.
Callback invoked with the raw AxonEventView for every event on the channel, regardless of origin.
An unsubscribe function that removes the listener.
Registers a listener for session/update notifications from the agent.
Callback invoked with the session ID and the update payload each time the agent emits a session update (message chunks, tool calls, etc.).
An unsubscribe function that removes the listener.
Registers a listener for classified timeline events (push API).
Every Axon event on the channel is classified into one of:
acp_protocol — a known ACP protocol event (agent or client method)system — a broker system event (turn.started, turn.completed, broker.error)unknown — anything elseFor a pull-based alternative, see receiveTimelineEvents. Both APIs deliver the same events; choose whichever fits your consumption pattern.
Callback invoked with each ACPTimelineEvent.
An unsubscribe function that removes the listener.
Sends a user prompt within a session and processes the agent's turn.
The returned promise resolves when the agent acknowledges the prompt, but session update notifications (tokens, tool calls, messages) may continue arriving after resolution. Listen via onSessionUpdate to capture the full turn.
Session ID and prompt content.
The agent's prompt acknowledgement.
Publishes a custom event to the Axon channel.
The event will appear in the SSE stream and be classified by the
timeline (typically as kind: "unknown" unless the event_type
matches a known ACP protocol method).
The event to publish (same shape as Axon.publish()).
The publish result with sequence number and timestamp.
Async generator that yields classified timeline events (pull API).
Mirrors the pull-based pattern of receiveMessages() in the Claude
module. The generator completes when the connection is disconnected
or the abort signal fires.
For a push-based alternative, see onTimelineEvent. Both APIs deliver the same events; choose whichever fits your consumption pattern.
An async generator of ACPTimelineEvent.
Sets a configuration option for a session.
Session ID, option key, and new value.
Confirmation of the configuration change.
Sets the operational mode for a session (e.g. "ask", "code").
Session ID and the target mode.
Confirmation of the mode change.
High-level ACP connection backed by an Axon transport.
Wraps a
ClientSideConnectionwith anaxonStream, providing:initialize,prompt,newSession, etc.)signal,closed,disconnect)The underlying
ClientSideConnectionis accessible via.protocolfor advanced use cases (e.g. unstable/experimental ACP methods).