use Raxol.AgentClientProtocol.Client to implement the client side of ACP: the editor/host process that answers permission asks, filesystem, and terminal requests, and receives session/update streaming notifications.

This is a thin ergonomic layer over Raxol.AgentClientProtocol.Connection -- see Raxol.AgentClientProtocol.Agent's moduledoc for the shared rationale (identical wiring, mirrored side). Nothing here re-implements protocol correlation, cancellation, or the turn/permission state machine; those live in Connection and (agent-side) Session.

Callback surface

One @callback per Raxol.AgentClientProtocol.MethodTable.rows_for_side(:client) row that carries an app-level callback -- session/request_permission, session/update, fs/write_text_file, fs/read_text_file, terminal/create, terminal/output, terminal/release, terminal/wait_for_exit, terminal/kill. Naming and arity are generated straight from the table, not hand-maintained; every current client row has params != nil, so every generated callback is arity 2: callback(params, ctx) (request or notification alike).

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 (client-role connections still get these two -- they are per-Connection infrastructure, not agent-specific).

A request callback (request_permission, write_text_file, read_text_file, the four terminal/* methods) returns {:ok, result_struct}, {:error, %Error{}}, or :deferred (legal only after Connection.delegate_reply/3). session_update/2's return value is always ignored (Router.dispatch/4) -- it is the streaming sink for session/update notifications during a prompt turn.

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()}, session_update/2 is a silent :ok. Override only what your client supports -- an unimplemented, capability-gated method never needs an explicit override (the client simply never advertises the capability at initialize, so a well-behaved agent never sends it; the -32601 default is the honest fallback if one does anyway). 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 MyClient do
  use Raxol.AgentClientProtocol.Client
  alias Raxol.AgentClientProtocol.Client.FsSandbox

  # `handler_arg:` is the project root the agent may read under.
  @impl true
  def init(root), do: {:ok, %{root: root}}

  @impl true
  def session_update(notification, _ctx) do
    IO.inspect(notification.update, label: "session/update")
  end

  @impl true
  def read_text_file(req, ctx), do: FsSandbox.read(ctx.handler_state.root, req)

  # ... only what you support.
end

{:ok, sup} =
  Raxol.AgentClientProtocol.Client.start_link(MyClient,
    transport: {mod, handle},
    handler_arg: "/path/to/project"
  )

Session-consumer ergonomics: subscribe / prompt / prompt_stream

Overriding session_update/2 yourself works fine, but most clients just want "give me the updates for session X" without hand-rolling a mailbox protocol. The generated default session_update/2 (unless you override it) forwards every decoded update to whichever processes called subscribe/3 for that {conn, session_id} pair, as {:acp_session_update, session_id, update} -- update is always an already-decoded Raxol.AgentClientProtocol.Schema.SessionUpdate.t() (see decode_update/1's doc for why an undecodable variant never reaches this path at all). subscribe/3 remains useful for a custom session_update/2 override that wants a broadcast fan-out, but it is NOT how prompt/3/prompt_stream/4 get their updates (see below).

{:ok, {updates, response}} =
  Client.prompt(client_conn, PromptRequest.new(session_id, prompt_blocks))

{:ok, response} =
  Client.prompt_stream(client_conn, request, fn update ->
    IO.inspect(update, label: "update")
  end)

prompt/3 and prompt_stream/4 drive the request through Connection.async_request/6 and then consume the direct turn-delivery channel (Raxol.AgentClientProtocol.Delivery's moduledoc): Connection opens a turn at submit time and, for every session/update belonging to that turn, sends the calling process {:acp_turn_update, tag, ordinal, notification} directly, itself -- the same single-sender operation it uses for the terminal {:acp_result, tag, outcome}. Because one process sends every update, the turn-end companion, and the result, BEAM's pairwise FIFO guarantees they arrive in wire order with NO reorder buffer, NO settle timer, and a synchronous, deterministic failure ({:error, {:delivery_gap, _}}) if the turn-end count and the delivered-update count ever disagree. This is why these two functions do not consume subscribe/3: that path runs a separate handler task per notification while the Connection sends the terminal result itself -- two different senders, no cross-sender FIFO guarantee.

fs_sandbox: a working filesystem client with zero callbacks

use Raxol.AgentClientProtocol.Client, fs_sandbox: "/path/to/root" auto- implements read_text_file/2 and write_text_file/2 (still defoverridable) confined to that directory: every request path is joined under the root, ..-normalized, and checked against the root using BOTH the lexical result and the fully symlink-resolved real path, so a ../ escape or a symlink planted inside the sandbox that points outside it are both rejected with -32602 invalid params. The file is then opened and the open handle checked to be the regular file that was resolved, and a read is capped at 16 MiB (fs_max_read_bytes: sets another cap). Raxol.AgentClientProtocol.Client.FsSandbox states what this does and does not guarantee against a peer that changes the sandbox tree while requests run. terminal/* handlers are deliberately NOT defaulted by any option here -- they stay method_not_found unless you implement them yourself.

Library-mode wiring

start_link/2 and child_spec/1 build exactly this subtree (identical shape to the agent side, role: :client):

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

See Raxol.AgentClientProtocol.Agent's moduledoc for why parent_sup is resolved via self() inside the nested supervisor's init/1 rather than passed in from outside. A client connection gets its own Session.Supervisor/SessionRegistry slot too -- unused, since the client side hosts no sessions, and kept only because the subtree shape is uniform across roles (one less special case in Connection).