@spec agent_capabilities(GenServer.server()) :: {:ok, map() | nil}

Returns the agent's capabilities from the initialize handshake.

@spec auth_methods(GenServer.server()) :: {:ok, [map()]}

Returns the agent's authentication methods from the initialize handshake.

@spec authenticate(GenServer.server(), String.t() | map(), keyword()) ::
  {:ok, map() | nil} | {:error, any()}

Authenticates with the agent.

Pass either a method ID advertised in the initialize response's "authMethods" list or a full params map for adapter compatibility.

@spec cancel(GenServer.server(), String.t()) :: :ok

Cancels the current prompt in a session (fire-and-forget).

Returns a specification to start this module under a supervisor.

See Supervisor.

@spec close_session(GenServer.server(), String.t(), keyword()) ::
  {:ok, map() | nil} | {:error, any()}

Closes an active session and frees agent-side resources.

@spec delete_session(GenServer.server(), String.t(), keyword()) ::
  {:ok, map() | nil} | {:error, any()}

Deletes a session from the agent's session history.

@spec disconnect(GenServer.server()) :: :ok

Disconnects from the agent.

@spec end_session(GenServer.server(), String.t()) ::
  :ok | {:ok, map() | nil} | {:error, any()}

Ends a session.

Uses session/close when advertised by the agent, otherwise preserves the historical local telemetry-only behavior.

@spec fork_session(GenServer.server(), String.t(), String.t(), keyword()) ::
  {:ok, map() | nil} | {:error, any()}

Forks an existing session into a new independent session.

session/fork is currently unstable in ACP and requires the agent to advertise sessionCapabilities.fork.

@spec list_sessions(
  GenServer.server(),
  keyword()
) :: {:ok, map()} | {:error, any()}

Lists available sessions from the agent. Stabilized in ACP spec March 9, 2026.

@spec load_session(GenServer.server(), String.t(), String.t(), keyword()) ::
  {:ok, map()} | {:error, any()}

Loads an existing session and replays previous messages when the agent supports it.

cwd is required per ACP spec.

@spec logout(
  GenServer.server(),
  keyword()
) :: {:ok, map() | nil} | {:error, any()}

Logs out of the current authenticated state if the agent supports auth.logout.

@spec new_session(GenServer.server(), String.t(), keyword()) ::
  {:ok, map()} | {:error, any()}

Creates a new agent session.

cwd is required per ACP spec (https://agentclientprotocol.com/protocol/session-setup).

@spec prompt(GenServer.server(), String.t(), String.t() | [map()], keyword()) ::
  {:ok, map()} | {:error, any()}

Sends a prompt to the agent and blocks until the response arrives.

Streaming session/update notifications are delivered to the handler and event listener as they arrive. The caller is unblocked when the agent sends the JSON-RPC result for the prompt request.

@spec resume_session(GenServer.server(), String.t(), String.t(), keyword()) ::
  {:ok, map() | nil} | {:error, any()}

Resumes an existing session without replaying previous messages.

cwd is required per ACP spec.

@spec set_config_option(GenServer.server(), String.t(), String.t(), any()) ::
  {:ok, map()} | {:error, any()}

Sets a config option for a session.

@spec set_mode(GenServer.server(), String.t(), String.t()) ::
  {:ok, map()} | {:error, any()}

Sets the agent mode for a session.

@spec set_model(GenServer.server(), String.t(), String.t()) ::
  {:ok, map()} | {:error, any()}

Sets the model for a session.

@spec start_link(keyword()) :: GenServer.on_start()

Starts the ACP client and connects to the agent.

@spec status(GenServer.server()) :: atom()

Returns the client connection status.