acp-sdk 0.13.0 → 0.14.0

data/lib/acp/agent_connection.rb

@@ -10,13 +10,62 @@ class ACP::AgentConnection
   # @rbs @extension_notifications: Hash[String, ^(untyped) -> void]
   # @rbs @logger: ACP::Transport::_Logger
 
-  # The schema has no initialize capability for modes or config options: an
-  # agent offers them per session, in its session responses, so they are
-  # routed whenever the agent defines them.
-  PER_SESSION = {
-    'session/set_mode' => :change_session_mode,
-    'session/set_config_option' => :change_session_config_option
-  }.freeze #: Hash[String, Symbol]
+  OPTIONAL_ROUTES = [
+    OptionalRoute.new(
+      rpc_method: 'authenticate',
+      type: ACP::Types::AuthenticateRequest,
+      agent_method: :authenticate,
+      path: %i[auth_methods any?]
+    ) { |agent, request| agent.authenticate(request) },
+    OptionalRoute.new(
+      rpc_method: 'session/load',
+      type: ACP::Types::LoadSessionRequest,
+      agent_method: :load_session,
+      path: %i[agent_capabilities load_session]
+    ) { |agent, request| agent.load_session(request) },
+    OptionalRoute.new(
+      rpc_method: 'session/list',
+      type: ACP::Types::ListSessionsRequest,
+      agent_method: :list_sessions,
+      path: %i[agent_capabilities session_capabilities list]
+    ) { |agent, request| agent.list_sessions(request) },
+    OptionalRoute.new(
+      rpc_method: 'session/resume',
+      type: ACP::Types::ResumeSessionRequest,
+      agent_method: :resume_session,
+      path: %i[agent_capabilities session_capabilities resume]
+    ) { |agent, request| agent.resume_session(request) },
+    OptionalRoute.new(
+      rpc_method: 'session/close',
+      type: ACP::Types::CloseSessionRequest,
+      agent_method: :close_session,
+      path: %i[agent_capabilities session_capabilities close]
+    ) { |agent, request| agent.close_session(request) },
+    OptionalRoute.new(
+      rpc_method: 'session/delete',
+      type: ACP::Types::DeleteSessionRequest,
+      agent_method: :delete_session,
+      path: %i[agent_capabilities session_capabilities delete]
+    ) { |agent, request| agent.delete_session(request) },
+    OptionalRoute.new(
+      rpc_method: 'logout',
+      type: ACP::Types::LogoutRequest,
+      agent_method: :logout,
+      path: %i[agent_capabilities auth logout]
+    ) { |agent, request| agent.logout(request) },
+    OptionalRoute.new(
+      rpc_method: 'session/set_mode',
+      type: ACP::Types::SetSessionModeRequest,
+      agent_method: :change_session_mode,
+      path: nil
+    ) { |agent, request| agent.change_session_mode(request) },
+    OptionalRoute.new(
+      rpc_method: 'session/set_config_option',
+      type: ACP::Types::SetSessionConfigOptionRequest,
+      agent_method: :change_session_config_option,
+      path: nil
+    ) { |agent, request| agent.change_session_config_option(request) }
+  ].freeze #: Array[ACP::AgentConnection::OptionalRoute]
 
   # @rbs transport: ACP::Transport::Stdio
   # @rbs capabilities: ACP::Types::AgentCapabilities
@@ -44,8 +93,7 @@ class ACP::AgentConnection
     @auth_methods = auth_methods
     @extension_requests = extension_requests
     @extension_notifications = extension_notifications
-    extension_requests.each_key { |name| ACP::Extensions.validate_name(name) }
-    extension_notifications.each_key { |name| ACP::Extensions.validate_name(name) }
+    ACP::Extensions.validate_names(extension_requests.keys + extension_notifications.keys)
     @factory = factory
   end
 
@@ -53,22 +101,23 @@ class ACP::AgentConnection
   def start
     client = ACP::AgentConnection::Client.new(peer: @transport, mcp_advertised: mcp_acp_advertised?)
     agent = @factory.call(client)
+    routes = OPTIONAL_ROUTES + unstable_routes
     # Routes are fixed before a client connects, so the check sees the
     # unfiltered auth methods: a terminal-capable client still needs
     # authenticate routed.
-    advertised, unadvertised = optional_methods.partition do |method|
-      method.advertised?(initialize_response(@auth_methods))
+    response = initialize_response(@auth_methods)
+    missing = routes.select { |route| route.advertised?(response) && !agent.respond_to?(route.agent_method) }
+    unless missing.empty?
+      raise ArgumentError, "initialize advertises methods the agent lacks: #{missing.map(&:agent_method).join(', ')}"
     end
-    missing = advertised.map(&:agent_method).reject { |name| agent.respond_to?(name) }
-    raise ArgumentError, "initialize advertises methods the agent lacks: #{missing.join(', ')}" unless missing.empty?
 
     if mcp_acp_advertised? && !agent.respond_to?(:mcp_message_notification)
       raise ArgumentError, 'initialize advertises mcpCapabilities.acp but the agent lacks mcp_message_notification'
     end
 
-    unrouted = unadvertised.map(&:rpc_method) + PER_SESSION.reject { |_, name| agent.respond_to?(name) }.keys
+    routed = routes.select { |route| route.routed?(response, agent) }
     @transport.start(
-      requests: requests(agent, client).except(*unrouted).merge(@extension_requests),
+      requests: requests(agent, client, routed).merge(@extension_requests),
       notifications: notifications(agent).merge(@extension_notifications)
     )
   end
@@ -77,56 +126,54 @@ class ACP::AgentConnection
 
   # @rbs agent: ACP::AgentConnection::_Agent
   # @rbs client: ACP::AgentConnection::Client
+  # @rbs optional: Array[ACP::AgentConnection::OptionalRoute]
   # @rbs return: Hash[String, ^(untyped) -> (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)]
-  def requests(agent, client)
-    # Safe: start drops the optional handlers initialize does not advertise
-    # or the agent does not define, and checks the agent defines the rest.
+  def requests(agent, client, optional)
+    # Safe: start passes only the optional routes the agent defines.
     full = agent #: ACP::AgentConnection::_FullAgent
+    optional_requests = optional.to_h do |entry|
+      [entry.rpc_method, route(entry.type) { |request| entry.handle.call(full, request) }]
+    end
     {
       'initialize' => route(ACP::Types::InitializeRequest) { |request| connect(client, request) },
-      'authenticate' => route(ACP::Types::AuthenticateRequest) { |request| full.authenticate(request) },
       'session/new' => route(ACP::Types::NewSessionRequest) { |request| new_session(agent, request) },
-      'session/prompt' => route(ACP::Types::PromptRequest) { |request| agent.prompt(request) },
-      'session/load' => route(ACP::Types::LoadSessionRequest) { |request| full.load_session(request) },
-      'session/list' => route(ACP::Types::ListSessionsRequest) { |request| full.list_sessions(request) },
-      'session/resume' => route(ACP::Types::ResumeSessionRequest) { |request| full.resume_session(request) },
-      'session/close' => route(ACP::Types::CloseSessionRequest) { |request| full.close_session(request) },
-      'session/delete' => route(ACP::Types::DeleteSessionRequest) { |request| full.delete_session(request) },
-      'logout' => route(ACP::Types::LogoutRequest) { |request| full.logout(request) },
-      'session/set_mode' => route(ACP::Types::SetSessionModeRequest) { |request| full.change_session_mode(request) },
-      'session/set_config_option' => route(ACP::Types::SetSessionConfigOptionRequest) do |request|
-        full.change_session_config_option(request)
-      end
-    }.merge(unstable_requests(full))
-  end
-
-  # The unstable request types are referenced while the hash is built, so
-  # without the guard start would raise NameError even for an agent that never
-  # advertises fork or providers.
-  #
-  # @rbs full: ACP::AgentConnection::_FullAgent
-  # @rbs return: Hash[String, ^(untyped) -> (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)]
-  def unstable_requests(full)
-    return {} unless ACP::Types.unstable_enabled?
-
-    {
-      'session/fork' => route(ACP::Types::Unstable::ForkSessionRequest) { |request| full.fork_session(request) },
-      'providers/list' => route(ACP::Types::Unstable::ListProvidersRequest) { |request| full.list_providers(request) },
-      'providers/set' => route(ACP::Types::Unstable::SetProviderRequest) { |request| full.set_provider(request) },
-      'providers/disable' => route(ACP::Types::Unstable::DisableProviderRequest) { |request| full.disable_provider(request) }
-    }
+      'session/prompt' => route(ACP::Types::PromptRequest) { |request| agent.prompt(request) }
+    }.merge(optional_requests)
   end
 
-  # The unstable specs pair with the unstable request routes, which reference
-  # the unstable request classes, so both are only probed after the caller
-  # opted in with `require 'acp/types/unstable'`.
-  #
-  # @rbs return: Array[ACP::AgentConnection::OptionalMethod::Spec]
-  def optional_methods
-    specs = ACP::AgentConnection::OptionalMethod::SPECS
-    return specs unless ACP::Types.unstable_enabled?
+  # @rbs return: Array[ACP::AgentConnection::OptionalRoute]
+  def unstable_routes
+    # The rows reference the unstable request types, so without the guard start
+    # would raise NameError even for an agent that never advertises fork or
+    # providers.
+    return [] unless ACP::Types.unstable_enabled?
 
-    specs + ACP::AgentConnection::OptionalMethod::UNSTABLE_SPECS
+    [
+      OptionalRoute.new(
+        rpc_method: 'session/fork',
+        type: ACP::Types::Unstable::ForkSessionRequest,
+        agent_method: :fork_session,
+        path: %i[agent_capabilities session_capabilities fork]
+      ) { |agent, request| agent.fork_session(request) },
+      OptionalRoute.new(
+        rpc_method: 'providers/list',
+        type: ACP::Types::Unstable::ListProvidersRequest,
+        agent_method: :list_providers,
+        path: %i[agent_capabilities providers]
+      ) { |agent, request| agent.list_providers(request) },
+      OptionalRoute.new(
+        rpc_method: 'providers/set',
+        type: ACP::Types::Unstable::SetProviderRequest,
+        agent_method: :set_provider,
+        path: %i[agent_capabilities providers]
+      ) { |agent, request| agent.set_provider(request) },
+      OptionalRoute.new(
+        rpc_method: 'providers/disable',
+        type: ACP::Types::Unstable::DisableProviderRequest,
+        agent_method: :disable_provider,
+        path: %i[agent_capabilities providers]
+      ) { |agent, request| agent.disable_provider(request) }
+    ]
   end
 
   # @rbs agent: ACP::AgentConnection::_Agent
@@ -144,11 +191,12 @@ class ACP::AgentConnection
   # @rbs params: untyped
   # @rbs return: void
   def cancel(agent, params)
-    notification = ACP::Types::CancelNotification.from_h(params)
-  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError => e
-    @logger.warn("dropped malformed session/cancel: #{e.class}: #{e.message}")
-  else
-    agent.cancel(notification)
+    notification = ACP::Types.parse(ACP::Types::CancelNotification, params)
+    if notification.is_a?(ACP::Types::ParseError)
+      @logger.warn("dropped malformed session/cancel: #{notification.message}")
+    else
+      agent.cancel(notification)
+    end
   end
 
   # @rbs return: bool
@@ -162,27 +210,23 @@ class ACP::AgentConnection
   # @rbs params: untyped
   # @rbs return: void
   def mcp_message_notification(agent, params)
-    notification = ACP::Types::Unstable::MessageMcpNotification.from_h(params)
-  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError => e
-    @logger.warn("dropped malformed mcp/message: #{e.class}: #{e.message}")
-  else
-    hook = agent #: ACP::AgentConnection::_Agent & ACP::AgentConnection::_McpMessageNotification
-    hook.mcp_message_notification(notification)
+    notification = ACP::Types.parse(ACP::Types::Unstable::MessageMcpNotification, params)
+    if notification.is_a?(ACP::Types::ParseError)
+      @logger.warn("dropped malformed mcp/message: #{notification.message}")
+    else
+      hook = agent #: ACP::AgentConnection::_Agent & ACP::AgentConnection::_McpMessageNotification
+      hook.mcp_message_notification(notification)
+    end
   end
 
-  # Generated from_h raises on a missing key or a value of the wrong shape.
-  #
   # @rbs type: ACP::Transport::_Parser
   # @rbs &handle: (untyped) -> (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)
   # @rbs return: ^(untyped) -> (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)
   def route(type, &)
     lambda do |params|
-      request = type.from_h(params)
-    rescue ACP::Types::ParseError => e
-      ACP::RequestError.invalid_params([e.message])
-    rescue KeyError, TypeError, NoMethodError
-      ACP::RequestError.invalid_params
-    else
+      request = ACP::Types.parse(type, params)
+      next ACP::RequestError.invalid_params([request.message]) if request.is_a?(ACP::Types::ParseError)
+
       yield(request)
     end
   end

data/lib/acp/agent_process.rb

@@ -48,7 +48,7 @@ class ACP::AgentProcess
     spawner = Open3.method(:popen2) #: _Spawner
     stdin, stdout, waiter = spawner.call(*(env ? [env, command, *args] : [command, *args]), **opts)
     err_w&.close
-    connection = ACP::ClientConnection.new(
+    connection = ACP::ClientConnection.build(
       transport: ACP::Transport::Stdio.new(input: stdout, output: stdin),
       permission:,
       updates:
@@ -65,14 +65,14 @@ class ACP::AgentProcess
 
   # @rbs return: void
   def terminate
-    @stdin.close unless @stdin.closed?
+    @stdin.close
     @waiter.join(1) or signal('TERM')
     @waiter.join(2) or signal('KILL')
     @waiter.join(2)
     @reader.join(1)
-    @stdout.close unless @stdout.closed?
+    @stdout.close
     @err_reader&.join(1)
-    @err_r&.close unless @err_r&.closed?
+    @err_r&.close
   end
 
   private

data/lib/acp/client_connection/elicitations.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+class ACP::ClientConnection::Elicitations
+  # @rbs @handler: ACP::ClientConnection::_Elicitation?
+  # @rbs @logger: ACP::Transport::_Logger
+  # @rbs @lock: Thread::Mutex
+  # @rbs @outstanding: Hash[String, bool]
+
+  # @rbs handler: ACP::ClientConnection::_Elicitation?
+  # @rbs logger: ACP::Transport::_Logger
+  # @rbs return: void
+  def initialize(handler:, logger:)
+    @handler = handler
+    @logger = logger
+    @lock = Mutex.new
+    @outstanding = {}
+  end
+
+  # @rbs elicitation_id: String
+  # @rbs return: void
+  def register(elicitation_id)
+    @lock.synchronize { @outstanding[elicitation_id] = true }
+  end
+
+  # The spec requires a completion for an unknown or already-completed
+  # elicitation id to be ignored, so only an id registered by a served
+  # url-mode request reaches the handler. It runs on the transport's reader
+  # thread, so it must return quickly.
+  #
+  # @rbs params: untyped
+  # @rbs return: void
+  def complete(params)
+    notification = ACP::Types.parse(ACP::Types::CompleteElicitationNotification, params)
+    if notification.is_a?(ACP::Types::ParseError)
+      @logger.warn("dropped malformed elicitation/complete: #{notification.message}")
+    else
+      known = @lock.synchronize { @outstanding.delete(notification.elicitation_id) }
+      handler = @handler
+      return unless known && handler
+
+      handler.complete_elicitation(notification) if handler.respond_to?(:complete_elicitation)
+    end
+  end
+end

data/lib/acp/client_connection/inbound/route.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+class ACP::ClientConnection::Inbound::Route
+  # @dynamic rpc_method
+  attr_reader :rpc_method #: String
+  # @dynamic type
+  attr_reader :type #: ACP::Transport::_Parser
+  # @dynamic handler_method
+  attr_reader :handler_method #: Symbol
+  # @dynamic path
+  attr_reader :path #: Array[Symbol]
+  # @dynamic capability
+  attr_reader :capability #: String
+
+  # @rbs rpc_method: String
+  # @rbs type: ACP::Transport::_Parser
+  # @rbs handler_method: Symbol
+  # @rbs path: Array[Symbol]
+  # @rbs capability: String
+  # @rbs return: void
+  def initialize(rpc_method:, type:, handler_method:, path:, capability:)
+    @rpc_method = rpc_method
+    @type = type
+    @handler_method = handler_method
+    @path = path.freeze
+    @capability = capability
+    freeze
+  end
+end

data/lib/acp/client_connection/inbound.rb

@@ -0,0 +1,232 @@
+# frozen_string_literal: true
+
+class ACP::ClientConnection::Inbound
+  # @rbs @fs: ACP::ClientConnection::_FileSystem?
+  # @rbs @terminal: ACP::ClientConnection::_Terminal?
+  # @rbs @elicitation: ACP::ClientConnection::_Elicitation?
+  # @rbs @elicitations: ACP::ClientConnection::Elicitations
+  # @rbs @mcp_message: (^(ACP::Types::Unstable::MessageMcpRequest) ->
+  #   (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError))?
+  # @rbs @extension_requests: Hash[String, ^(untyped) -> untyped]
+  # @rbs @extension_notifications: Hash[String, ^(untyped) -> void]
+  # @rbs @capabilities: ACP::Types::ClientCapabilities?
+
+  FS_ROUTES = [
+    Route.new(
+      rpc_method: 'fs/read_text_file',
+      type: ACP::Types::ReadTextFileRequest,
+      handler_method: :read_text_file,
+      path: %i[fs read_text_file],
+      capability: 'fs.readTextFile'
+    ),
+    Route.new(
+      rpc_method: 'fs/write_text_file',
+      type: ACP::Types::WriteTextFileRequest,
+      handler_method: :write_text_file,
+      path: %i[fs write_text_file],
+      capability: 'fs.writeTextFile'
+    )
+  ].freeze #: Array[ACP::ClientConnection::Inbound::Route]
+
+  # The terminal capability is a single bool, so its five routes share one
+  # gate. Their handlers may block for as long as the command runs, so the
+  # transport must serve each request on its own thread for this not to hold
+  # up others.
+  TERMINAL_ROUTES = [
+    Route.new(
+      rpc_method: 'terminal/create',
+      type: ACP::Types::CreateTerminalRequest,
+      handler_method: :create_terminal,
+      path: %i[terminal],
+      capability: 'terminal'
+    ),
+    Route.new(
+      rpc_method: 'terminal/output',
+      type: ACP::Types::TerminalOutputRequest,
+      handler_method: :terminal_output,
+      path: %i[terminal],
+      capability: 'terminal'
+    ),
+    Route.new(
+      rpc_method: 'terminal/wait_for_exit',
+      type: ACP::Types::WaitForTerminalExitRequest,
+      handler_method: :wait_for_terminal_exit,
+      path: %i[terminal],
+      capability: 'terminal'
+    ),
+    Route.new(
+      rpc_method: 'terminal/kill',
+      type: ACP::Types::KillTerminalRequest,
+      handler_method: :kill_terminal,
+      path: %i[terminal],
+      capability: 'terminal'
+    ),
+    Route.new(
+      rpc_method: 'terminal/release',
+      type: ACP::Types::ReleaseTerminalRequest,
+      handler_method: :release_terminal,
+      path: %i[terminal],
+      capability: 'terminal'
+    )
+  ].freeze #: Array[ACP::ClientConnection::Inbound::Route]
+
+  # @dynamic mcp_advertised=
+  attr_writer :mcp_advertised #: bool
+
+  # @rbs elicitations: ACP::ClientConnection::Elicitations
+  # @rbs fs: ACP::ClientConnection::_FileSystem?
+  # @rbs terminal: ACP::ClientConnection::_Terminal?
+  # @rbs elicitation: ACP::ClientConnection::_Elicitation?
+  # @rbs mcp_message: (^(ACP::Types::Unstable::MessageMcpRequest) ->
+  #   (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError))?
+  # @rbs extension_requests: Hash[String, ^(untyped) -> untyped]
+  # @rbs extension_notifications: Hash[String, ^(untyped) -> void]
+  # @rbs return: void
+  def initialize(
+    elicitations:,
+    fs: nil, # rubocop:disable Naming/MethodParameterName -- named after ClientCapabilities#fs
+    terminal: nil,
+    elicitation: nil,
+    mcp_message: nil,
+    extension_requests: {},
+    extension_notifications: {}
+  )
+    ACP::Extensions.validate_names(extension_requests.keys + extension_notifications.keys)
+    @elicitations = elicitations
+    @fs = fs
+    @terminal = terminal
+    @elicitation = elicitation
+    @mcp_message = mcp_message
+    @extension_requests = extension_requests
+    @extension_notifications = extension_notifications
+    @capabilities = nil
+    @mcp_advertised = false
+  end
+
+  # @rbs return: Hash[String, ACP::Transport::Stdio::_Handler]
+  def requests
+    {
+      **FS_ROUTES.to_h { |route| [route.rpc_method, serve(route, @fs)] },
+      **TERMINAL_ROUTES.to_h { |route| [route.rpc_method, serve(route, @terminal)] },
+      'elicitation/create' => method(:create_elicitation),
+      **mcp_requests,
+      **@extension_requests
+    }
+  end
+
+  # @rbs return: Hash[String, ACP::Transport::Stdio::_NotificationHandler]
+  def notifications
+    { 'elicitation/complete' => @elicitations.method(:complete), **@extension_notifications }
+  end
+
+  # @rbs capabilities: ACP::Types::ClientCapabilities?
+  # @rbs return: void
+  def advertise(capabilities)
+    check_served('fs methods', unserved(FS_ROUTES, @fs, capabilities))
+    check_served('terminal methods', unserved(TERMINAL_ROUTES, @terminal, capabilities))
+    check_served('elicitation modes', unserved_elicitation_modes(capabilities&.elicitation))
+    @capabilities = capabilities
+  end
+
+  private
+
+  # @rbs route: ACP::ClientConnection::Inbound::Route
+  # @rbs handler: untyped
+  # @rbs return: ^(untyped) -> untyped
+  def serve(route, handler)
+    lambda do |params|
+      # The routes are registered at start, before connect advertises the
+      # capabilities, so each one refuses until then.
+      next ACP::RequestError.unadvertised(route.capability) unless ACP::Protocol.advertised?(@capabilities, route.path)
+
+      # Safe: advertise refuses an advertised capability no handler serves.
+      parsed(route.type, params) { |request| handler.public_send(route.handler_method, request) }
+    end
+  end
+
+  # @rbs type: ACP::Transport::_Parser
+  # @rbs params: untyped
+  # @rbs &block: (untyped) -> untyped
+  # @rbs return: untyped
+  def parsed(type, params)
+    request = ACP::Types.parse(type, params)
+    request.is_a?(ACP::Types::ParseError) ? ACP::RequestError.invalid_params([request.message]) : yield(request)
+  end
+
+  # @rbs routes: Array[ACP::ClientConnection::Inbound::Route]
+  # @rbs handler: untyped
+  # @rbs capabilities: ACP::Types::ClientCapabilities?
+  # @rbs return: Array[String]
+  def unserved(routes, handler, capabilities)
+    routes.filter_map do |route|
+      next unless ACP::Protocol.advertised?(capabilities, route.path)
+
+      route.handler_method.to_s unless handler.respond_to?(route.handler_method)
+    end
+  end
+
+  # @rbs capabilities: ACP::Types::ElicitationCapabilities?
+  # @rbs return: Array[String]
+  def unserved_elicitation_modes(capabilities)
+    return [] if @elicitation.respond_to?(:create_elicitation)
+
+    { 'elicitation.form' => capabilities&.form, 'elicitation.url' => capabilities&.url }.select { |_, on| on }.keys
+  end
+
+  # @rbs what: String
+  # @rbs unserved: Array[String]
+  # @rbs return: void
+  def check_served(what, unserved)
+    return if unserved.empty?
+
+    raise ArgumentError, "initialize advertises #{what} no handler serves: #{unserved.join(', ')}"
+  end
+
+  # @rbs return: Hash[String, ^(untyped) -> untyped]
+  def mcp_requests
+    handler = @mcp_message
+    # Registered only when a handler serves it: unlike the fs and terminal gates,
+    # the mcp gate reads the agent's advertisement, so nothing forces an
+    # advertised request to have a handler. The route references the unstable
+    # types, so it needs the caller's `require 'acp/types/unstable'` too.
+    return {} unless handler && ACP::Types.unstable_enabled?
+
+    route = lambda do |params|
+      next ACP::RequestError.unadvertised_agent('mcpCapabilities.acp') unless @mcp_advertised
+
+      parsed(ACP::Types::Unstable::MessageMcpRequest, params) { |request| handler.call(request) }
+    end
+    { 'mcp/message' => route }
+  end
+
+  # @rbs params: untyped
+  # @rbs return: (ACP::Types::CreateElicitationResponse | ACP::RequestError)
+  def create_elicitation(params)
+    parsed(ACP::Types::CreateElicitationRequest, params) do |request|
+      refusal = elicitation_refusal(request)
+      next refusal if refusal
+
+      mode = request.mode
+      @elicitations.register(mode.elicitation_id) if mode.is_a?(ACP::Types::CreateElicitationRequest::Mode::Url)
+      # Safe: advertise refuses an advertised mode no handler serves.
+      handler = @elicitation #: ACP::ClientConnection::_Elicitation
+      handler.create_elicitation(request)
+    end
+  end
+
+  # @rbs request: ACP::Types::CreateElicitationRequest
+  # @rbs return: ACP::RequestError?
+  def elicitation_refusal(request)
+    modes = @capabilities&.elicitation
+    # An unadvertised mode answers -32602 rather than -32601: the spec gives
+    # elicitation its mode in the params.
+    case request.mode
+    when ACP::Types::CreateElicitationRequest::Mode::Form
+      ACP::RequestError.unadvertised_mode('elicitation.form') unless modes&.form
+    when ACP::Types::CreateElicitationRequest::Mode::Url
+      ACP::RequestError.unadvertised_mode('elicitation.url') unless modes&.url
+    else
+      ACP::RequestError.unadvertised_mode("elicitation.#{request.mode['mode']}")
+    end
+  end
+end