use Raxol.AgentClientProtocol.Agent to implement the agent side of ACP: the process that answers initialize, creates/loads sessions, and serves session/prompt turns.

This is a thin ergonomic layer over Raxol.AgentClientProtocol.Connection and Raxol.AgentClientProtocol.Session: it only generates the callback surface and wires the supervision tree. Protocol correlation, cancellation, permission fan-out, and turn/streaming semantics live entirely in those two modules -- nothing here re-implements or shortcuts them.

Callback surface

One @callback per Raxol.AgentClientProtocol.MethodTable.rows_for_side(:agent) row that carries an app-level callback (layer: :app -- everything except session/cancel, which is Connection-routed session control with no handler callback at all). Naming and arity are generated straight from the table, not hand-maintained:

• params: nil rows (currently only logout) get callback arity 1: callback(ctx).
• every other row gets arity 2: callback(params, ctx) for requests, callback(notification, ctx) for notifications.

ctx is Raxol.AgentClientProtocol.Connection.Ctx.t(): read-only per dispatch, carries conn (the Connection pid, for Connection.request/async_request/notify/reply/delegate_reply), handler_state (produced once by init/1), reply_ref, rx_seq, session_sup, task_sup.

A request callback returns {:ok, result_struct}, {:error, %Error{}}, or :deferred (legal only after Connection.delegate_reply/3; a :deferred return without a prior delegation is a contract breach the Connection turns into -32603). A notification callback's return value is always ignored (Router.dispatch/4).

Call callbacks/0 to introspect the generated {callback, arity, wire} list.

Defaults

Every generated callback (and handle_ext_request/3, handle_ext_notification/3) has an overridable default: requests answer {:error, Error.method_not_found()}, notifications are a silent :ok. Override only what your agent supports -- an unimplemented, capability-gated method (e.g. session/load without loadSession advertised) never needs an explicit override, the wire-correct -32601 falls out for free. init/1 defaults to {:ok, handler_arg}.

Extension methods

"_"-prefixed wire methods with no MethodTable row are routed by Connection directly to handle_ext_request/3 / handle_ext_notification/3 (never through the table-driven callbacks above -- see Router's moduledoc). Both default the same way as any other unsupported method.

Example

defmodule MyAgent do
  use Raxol.AgentClientProtocol.Agent
  alias Raxol.AgentClientProtocol.Schema.AgentTypes.InitializeResponse

  @impl true
  def init(_arg), do: {:ok, %{sessions: %{}}}

  @impl true
  def initialize(_req, _ctx), do: {:ok, InitializeResponse.new(1)}

  # ... new_session/2, prompt/2, etc. -- only what you support.
end

{:ok, sup} = Raxol.AgentClientProtocol.Agent.start_link(MyAgent, transport: {mod, handle})

Library-mode wiring

start_link/2 and child_spec/1 build exactly this subtree:

ConnectionSupervisor          Supervisor, :one_for_all,
│                             auto_shutdown: :any_significant
├── Task.Supervisor           restart: :permanent
├── DynamicSupervisor         restart: :permanent  (Session.Supervisor; :temporary children)
└── Connection                restart: :temporary, significant: true

Connection resolves its task_sup/session_sup siblings via Supervisor.which_children/1 in handle_continue/2 (never in init/1), so this layer does not need to name or pre-register them; it only needs to hand Connection the ConnectionSupervisor's own pid as parent_sup, which the nested ConnectionSupervisor.init/1 callback captures via self() (that callback body runs in the supervisor process, before any child starts -- the standard OTP way to hand a supervisor's own pid to a child it is about to start).