acp-sdk 0.9.0 → 0.11.0

data/lib/acp/client_connection.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class ACP::ClientConnection
-  # @rbs @transport: ACP::AgentConnection::_Transport
+  # @rbs @transport: ACP::Transport::_Transport
   # @rbs @permission: ACP::ClientConnection::_PermissionHandler
   # @rbs @read_text_file: (^(ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError))?
   # @rbs @write_text_file: (^(ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError))?
@@ -13,28 +13,139 @@ class ACP::ClientConnection
   # @rbs @release_terminal: (^(ACP::Types::ReleaseTerminalRequest) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError))?
   # @rbs @elicitation: (^(ACP::Types::CreateElicitationRequest) ->
   #   (ACP::Types::CreateElicitationResponse | ACP::RequestError))?
-  # @rbs @complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?
-  # @rbs @updates: ACP::ClientConnection::_UpdateHandler
+  # @rbs @mcp_message: (^(ACP::Types::Unstable::MessageMcpRequest) ->
+  #   (ACP::Types::Unstable::MessageMcpResponse::t | ACP::RequestError))?
+  # @rbs @mcp_advertised: bool?
   # @rbs @fs_capabilities: ACP::Types::FileSystemCapabilities?
   # @rbs @terminal: bool?
   # @rbs @elicitation_capabilities: ACP::Types::ElicitationCapabilities?
   # @rbs @extension_requests: Hash[String, ^(untyped) -> untyped]
   # @rbs @extension_notifications: Hash[String, ^(untyped) -> void]
-  # @rbs @lock: Thread::Mutex
-  # @rbs @streams: Hash[String, Thread::Queue]
-  # @rbs @pending_permissions: Hash[String, Array[Thread::Queue]]
-  # @rbs @outstanding_elicitations: Hash[String, bool]
+  # @rbs @streams: ACP::ClientConnection::Streams
   # @rbs @logger: ACP::Transport::_Logger
 
-  PROTOCOL_VERSION = ACP::AgentConnection::PROTOCOL_VERSION #: Integer
-
   IGNORE = ->(_notification) {} #: ^(ACP::Types::SessionNotification) -> void
 
-  CANCELLED = ACP::Types::RequestPermissionResponse.new(
-    outcome: ACP::Types::RequestPermissionOutcome::Cancelled.new
-  ) #: ACP::Types::RequestPermissionResponse
+  class Route
+    # @rbs @wire: String
+    # @rbs @type: ACP::Transport::_Parser
+    # @rbs @handler: Symbol
+    # @rbs @family: Symbol
+    # @rbs @advertised: ^(untyped) -> (bool | nil)
+    # @rbs @refuse: Symbol
+    # @rbs @key: String
+    # @rbs @label: String
+
+    # @rbs wire: String
+    # @rbs type: ACP::Transport::_Parser
+    # @rbs handler: Symbol
+    # @rbs family: Symbol
+    # @rbs key: String
+    # @rbs advertised: ^(untyped) -> (bool | nil)
+    # @rbs refuse: Symbol
+    # @rbs label: String?
+    # @rbs return: void
+    def initialize(
+      wire:,
+      type:,
+      handler:,
+      family:,
+      key:,
+      advertised: ->(caps) { caps },
+      refuse: :unadvertised,
+      label: nil
+    )
+      @wire = wire
+      @type = type
+      @handler = handler
+      @family = family
+      @advertised = advertised
+      @refuse = refuse
+      @key = key
+      # The capability key connect's pre-flight names; it differs from the
+      # refusal key where a family gates several routes at once.
+      @label = label || key
+      freeze
+    end
+
+    # @dynamic wire, type, handler, family, advertised, refuse, key, label
+    attr_reader :wire #: String
+    attr_reader :type #: ACP::Transport::_Parser
+    attr_reader :handler #: Symbol
+    attr_reader :family #: Symbol
+    attr_reader :advertised #: ^(untyped) -> (bool | nil)
+    attr_reader :refuse #: Symbol
+    attr_reader :key #: String
+    attr_reader :label #: String
+  end
+
+  # The routes are registered at start, before connect records the
+  # advertisement, so each one answers its refusal until then. The terminal
+  # capability is a single bool, so its five routes share one gate.
+  #
+  # The terminal 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.
+  SERVE = [
+    Route.new(
+      wire: 'fs/read_text_file',
+      type: ACP::Types::ReadTextFileRequest,
+      handler: :@read_text_file,
+      family: :@fs_capabilities,
+      advertised: ->(caps) { caps&.read_text_file },
+      key: 'fs.readTextFile'
+    ),
+    Route.new(
+      wire: 'fs/write_text_file',
+      type: ACP::Types::WriteTextFileRequest,
+      handler: :@write_text_file,
+      family: :@fs_capabilities,
+      advertised: ->(caps) { caps&.write_text_file },
+      key: 'fs.writeTextFile'
+    ),
+    Route.new(
+      wire: 'terminal/create',
+      type: ACP::Types::CreateTerminalRequest,
+      handler: :@create_terminal,
+      family: :@terminal,
+      key: 'terminal',
+      label: 'terminal.create'
+    ),
+    Route.new(
+      wire: 'terminal/output',
+      type: ACP::Types::TerminalOutputRequest,
+      handler: :@terminal_output,
+      family: :@terminal,
+      key: 'terminal',
+      label: 'terminal.output'
+    ),
+    Route.new(
+      wire: 'terminal/wait_for_exit',
+      type: ACP::Types::WaitForTerminalExitRequest,
+      handler: :@wait_for_terminal_exit,
+      family: :@terminal,
+      key: 'terminal',
+      label: 'terminal.wait_for_exit'
+    ),
+    Route.new(
+      wire: 'terminal/kill',
+      type: ACP::Types::KillTerminalRequest,
+      handler: :@kill_terminal,
+      family: :@terminal,
+      key: 'terminal',
+      label: 'terminal.kill'
+    ),
+    Route.new(
+      wire: 'terminal/release',
+      type: ACP::Types::ReleaseTerminalRequest,
+      handler: :@release_terminal,
+      family: :@terminal,
+      key: 'terminal',
+      label: 'terminal.release'
+    )
+  ].freeze #: Array[ACP::ClientConnection::Route]
 
-  # @rbs transport: ACP::AgentConnection::_Transport
+  # @rbs transport: ACP::Transport::_Transport
   # @rbs permission: ACP::ClientConnection::_PermissionHandler
   # @rbs read_text_file: (^(ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError))?
   # @rbs write_text_file: (^(ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError))?
@@ -48,8 +159,11 @@ class ACP::ClientConnection
   #   (ACP::Types::CreateElicitationResponse | ACP::RequestError))?
   # @rbs complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?
   # @rbs updates: ACP::ClientConnection::_UpdateHandler
+  # @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 streams: ACP::ClientConnection::Streams?
   # @rbs logger: ACP::Transport::_Logger
   # @rbs return: void
   def initialize(
@@ -65,12 +179,13 @@ class ACP::ClientConnection
     elicitation: nil,
     complete_elicitation: nil,
     updates: IGNORE,
+    mcp_message: nil,
     extension_requests: {},
     extension_notifications: {},
+    streams: nil,
     logger: ACP::Transport::StderrLogger.new
   )
     @transport = transport
-    @permission = permission
     @read_text_file = read_text_file
     @write_text_file = write_text_file
     @create_terminal = create_terminal
@@ -79,8 +194,8 @@ class ACP::ClientConnection
     @kill_terminal = kill_terminal
     @release_terminal = release_terminal
     @elicitation = elicitation
-    @complete_elicitation = complete_elicitation
-    @updates = updates
+    @mcp_message = mcp_message
+    @mcp_advertised = nil
     @fs_capabilities = nil
     @terminal = nil
     @elicitation_capabilities = nil
@@ -88,10 +203,7 @@ class ACP::ClientConnection
     @extension_notifications = extension_notifications
     extension_requests.each_key { |name| ACP::Extensions.validate_name(name) }
     extension_notifications.each_key { |name| ACP::Extensions.validate_name(name) }
-    @lock = Mutex.new
-    @streams = {}
-    @pending_permissions = {}
-    @outstanding_elicitations = {}
+    @streams = streams || Streams.new(sender: transport, permission:, updates:, logger:, complete_elicitation:)
     @logger = logger
   end
 
@@ -99,18 +211,13 @@ class ACP::ClientConnection
   def start
     @transport.start(
       requests: {
-        'session/request_permission' => method(:request_permission),
-        'fs/read_text_file' => method(:read_text_file),
-        'fs/write_text_file' => method(:write_text_file),
-        'terminal/create' => method(:create_terminal),
-        'terminal/output' => method(:terminal_output),
-        'terminal/wait_for_exit' => method(:wait_for_terminal_exit),
-        'terminal/kill' => method(:kill_terminal),
-        'terminal/release' => method(:release_terminal),
+        'session/request_permission' => @streams.method(:request_permission),
         'elicitation/create' => method(:create_elicitation)
-      }.merge(@extension_requests),
-      notifications: { 'session/update' => method(:dispatch),
-                       'elicitation/complete' => method(:complete_elicitation) }.merge(@extension_notifications)
+      }.merge(SERVE.to_h { |route| [route.wire, serve(route)] }).merge(mcp_requests).merge(@extension_requests),
+      notifications: {
+        'session/update' => @streams.method(:dispatch),
+        'elicitation/complete' => @streams.method(:complete_elicitation)
+      }.merge(@extension_notifications)
     )
   end
 
@@ -120,102 +227,124 @@ class ACP::ClientConnection
   # @rbs request: ACP::Types::InitializeRequest
   # @rbs return: ACP::Types::InitializeResponse | ACP::RequestError
   def connect(request)
-    capabilities = request.client_capabilities&.fs
-    unserved = unserved_fs_methods(capabilities)
-    unless unserved.empty?
-      raise ArgumentError, "initialize advertises fs methods no handler serves: #{unserved.join(', ')}"
-    end
+    capabilities = request.client_capabilities
+    fs = capabilities&.fs
+    terminal = capabilities&.terminal
+    check_served('fs', :@fs_capabilities, fs)
+    check_served('terminal', :@terminal, terminal)
 
-    terminal = request.client_capabilities&.terminal
-    unserved = unserved_terminal_methods(terminal)
-    unless unserved.empty?
-      raise ArgumentError, "initialize advertises terminal methods no handler serves: #{unserved.join(', ')}"
-    end
-
-    elicitation = request.client_capabilities&.elicitation
+    elicitation = capabilities&.elicitation
     unserved = unserved_elicitation_modes(elicitation)
     unless unserved.empty?
       raise ArgumentError, "initialize advertises elicitation modes no handler serves: #{unserved.join(', ')}"
     end
 
-    @fs_capabilities = capabilities
+    @fs_capabilities = fs
     @terminal = terminal
     @elicitation_capabilities = elicitation
-    parse(ACP::Types::InitializeResponse, @transport.request('initialize', request.to_h)).then do |response|
-      next response if response.is_a?(ACP::RequestError)
-
-      next response if response.protocol_version == PROTOCOL_VERSION
-
-      ACP::RequestError.unsupported_protocol_version(
-        requested: request.protocol_version,
-        returned: response.protocol_version
-      )
-    end
+    result = @transport.request('initialize', request.to_h)
+    response = parse(ACP::Types::InitializeResponse, result)
+    return response if response.is_a?(ACP::RequestError)
+
+    # Safe: parse only calls from_h on a Hash, and its RequestError answer
+    # short-circuited above.
+    reply = result #: Hash[String, untyped]
+    @mcp_advertised = ACP::Protocol.mcp_acp_advertised?(reply['agentCapabilities'] || {})
+    return response if response.protocol_version == ACP::Protocol::PROTOCOL_VERSION
+
+    ACP::RequestError.unsupported_protocol_version(
+      requested: request.protocol_version,
+      returned: response.protocol_version
+    )
   end
 
   # @rbs request: ACP::Types::NewSessionRequest
   # @rbs return: ACP::Types::NewSessionResponse | ACP::RequestError
-  def session_new(request)
+  def new_session(request)
     parse(ACP::Types::NewSessionResponse, @transport.request('session/new', request.to_h))
   end
 
   # @rbs request: ACP::Types::PromptRequest
   # @rbs &block: (ACP::Types::SessionUpdate::t) -> void
   # @rbs return: ACP::Types::PromptResponse | ACP::RequestError
-  def session_prompt(request, &)
-    parse(ACP::Types::PromptResponse, stream(request.session_id, 'session/prompt', request.to_h, &))
+  def prompt_session(request, &)
+    parse(ACP::Types::PromptResponse, @streams.stream(request.session_id, 'session/prompt', request.to_h, &))
   end
 
   # @rbs request: ACP::Types::LoadSessionRequest
   # @rbs &block: (ACP::Types::SessionUpdate::t) -> void
   # @rbs return: ACP::Types::LoadSessionResponse | ACP::RequestError
-  def session_load(request, &)
-    parse(ACP::Types::LoadSessionResponse, stream(request.session_id, 'session/load', request.to_h, &))
+  def load_session(request, &)
+    parse(ACP::Types::LoadSessionResponse, @streams.stream(request.session_id, 'session/load', request.to_h, &))
   end
 
   # @rbs request: ACP::Types::ListSessionsRequest
   # @rbs return: ACP::Types::ListSessionsResponse | ACP::RequestError
-  def session_list(request)
+  def list_sessions(request)
     parse(ACP::Types::ListSessionsResponse, @transport.request('session/list', request.to_h))
   end
 
-  # The agent does not replay history on resume, so unlike session_load there
+  # The agent does not replay history on resume, so unlike load_session there
   # is nothing to stream and no block is taken.
   #
   # @rbs request: ACP::Types::ResumeSessionRequest
   # @rbs return: ACP::Types::ResumeSessionResponse | ACP::RequestError
-  def session_resume(request)
+  def resume_session(request)
     parse(ACP::Types::ResumeSessionResponse, @transport.request('session/resume', request.to_h))
   end
 
   # @rbs request: ACP::Types::CloseSessionRequest
   # @rbs return: ACP::Types::CloseSessionResponse | ACP::RequestError
-  def session_close(request)
+  def close_session(request)
     parse(ACP::Types::CloseSessionResponse, @transport.request('session/close', request.to_h))
   end
 
   # @rbs request: ACP::Types::DeleteSessionRequest
   # @rbs return: ACP::Types::DeleteSessionResponse | ACP::RequestError
-  def session_delete(request)
+  def delete_session(request)
     parse(ACP::Types::DeleteSessionResponse, @transport.request('session/delete', request.to_h))
   end
 
+  # @rbs request: ACP::Types::Unstable::ForkSessionRequest
+  # @rbs return: (ACP::Types::Unstable::ForkSessionResponse | ACP::RequestError)
+  def fork_session(request)
+    parse(ACP::Types::Unstable::ForkSessionResponse, @transport.request('session/fork', request.to_h))
+  end
+
+  # @rbs request: ACP::Types::Unstable::ListProvidersRequest
+  # @rbs return: (ACP::Types::Unstable::ListProvidersResponse | ACP::RequestError)
+  def list_providers(request)
+    parse(ACP::Types::Unstable::ListProvidersResponse, @transport.request('providers/list', request.to_h))
+  end
+
+  # @rbs request: ACP::Types::Unstable::SetProviderRequest
+  # @rbs return: (ACP::Types::Unstable::SetProviderResponse | ACP::RequestError)
+  # The name is the wire-mandated providers/set, not an attribute writer.
+  def set_provider(request) # rubocop:disable Naming/AccessorMethodName
+    parse(ACP::Types::Unstable::SetProviderResponse, @transport.request('providers/set', request.to_h))
+  end
+
+  # @rbs request: ACP::Types::Unstable::DisableProviderRequest
+  # @rbs return: (ACP::Types::Unstable::DisableProviderResponse | ACP::RequestError)
+  def disable_provider(request)
+    parse(ACP::Types::Unstable::DisableProviderResponse, @transport.request('providers/disable', request.to_h))
+  end
+
   # The spec requires a pending session/request_permission to be answered with
-  # the cancelled outcome once the turn is cancelled, so every queue registered
-  # for the session gets one before this returns. The notification goes first
-  # so the wire order is cancel, then the cancelled replies.
+  # the cancelled outcome once the turn is cancelled. The notification goes
+  # first so the wire order is cancel, then the cancelled replies.
   #
   # @rbs notification: ACP::Types::CancelNotification
   # @rbs return: void
-  def session_cancel(notification)
+  def cancel_session(notification)
     @transport.notify('session/cancel', notification.to_h)
-    pending = @lock.synchronize { @pending_permissions.delete(notification.session_id) }
-    pending&.each { |replies| replies << [:value, CANCELLED] }
+    @streams.cancel(notification.session_id)
   end
 
   # @rbs request: ACP::Types::SetSessionModeRequest
   # @rbs return: ACP::Types::SetSessionModeResponse | ACP::RequestError
-  def session_set_mode(request)
+  # The name is the wire-mandated session/set_mode, not an attribute writer.
+  def set_session_mode(request) # rubocop:disable Naming/AccessorMethodName
     parse(ACP::Types::SetSessionModeResponse, @transport.request('session/set_mode', request.to_h))
   end
 
@@ -224,7 +353,8 @@ class ACP::ClientConnection
   #
   # @rbs request: ACP::Types::SetSessionConfigOptionRequest
   # @rbs return: ACP::Types::SetSessionConfigOptionResponse | ACP::RequestError
-  def session_set_config_option(request)
+  # The name is the wire-mandated session/set_config_option, not an attribute writer.
+  def set_session_config_option(request) # rubocop:disable Naming/AccessorMethodName
     parse(ACP::Types::SetSessionConfigOptionResponse, @transport.request('session/set_config_option', request.to_h))
   end
 
@@ -240,9 +370,7 @@ class ACP::ClientConnection
     parse(ACP::Types::LogoutResponse, @transport.request('logout', request.to_h))
   end
 
-  # Sends an extension request, keyed by its raw `_`-prefixed wire name, and
-  # returns the agent's reply as-is: extension methods have no schema to
-  # parse the result into.
+  # Extension methods have no schema to parse the result into.
   #
   # @rbs method: String
   # @rbs params: untyped
@@ -252,6 +380,13 @@ class ACP::ClientConnection
     @transport.request(method, params)
   end
 
+  # Always false off a handler thread.
+  #
+  # @rbs return: bool
+  def cancelled?
+    !!@transport.cancellation&.cancelled?
+  end
+
   # @rbs method: String
   # @rbs params: untyped
   # @rbs return: void
@@ -260,243 +395,101 @@ class ACP::ClientConnection
     @transport.notify(method, params)
   end
 
-  private
-
-  # @rbs type: ACP::AgentConnection::_Parser
-  # @rbs result: (Hash[String, untyped] | ACP::RequestError)
-  # @rbs return: untyped
-  def parse(type, result)
-    return result if result.is_a?(ACP::RequestError)
-
-    type.from_h(result)
-  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError
-    ACP::RequestError.invalid_response(result)
-  end
-
-  # The request waits on its own thread so the caller's thread can yield each
-  # update as it arrives. The reader thread queues an update before it settles
-  # a reply sent after it, so the queue closes only after the last one.
+  # Unlike the mcp/message serve route, this send is not gated: a notification
+  # has no reply to carry a refusal, and the agent drops what it did not
+  # advertise.
   #
-  # @rbs session_id: String
-  # @rbs method: String
-  # @rbs params: Hash[String, untyped]
-  # @rbs &block: (ACP::Types::SessionUpdate::t) -> void
-  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
-  def stream(session_id, method, params)
-    queue = Thread::Queue.new
-    # The check and the insert share one lock acquisition so a concurrent
-    # stream cannot register between them.
-    claimed = @lock.synchronize do
-      if @streams.key?(session_id)
-        false
-      else
-        @streams[session_id] = queue
-        true
-      end
-    end
-    unless claimed
-      return ACP::RequestError.new(
-        code: ACP::RequestError::INVALID_REQUEST, message: "A stream is already open for session #{session_id}"
-      )
-    end
-    requester = Thread.new do
-      @transport.request(method, params)
-    ensure
-      @lock.synchronize { @streams.delete(session_id)&.close }
-    end
-    while (update = queue.pop)
-      yield update
-    end
-    requester.value
-  end
-
-  # Pushes under the lock so a stream cannot close its queue between the
-  # lookup and the push. A malformed notification has no reply to carry the
-  # failure.
-  #
-  # @rbs params: untyped
+  # @rbs notification: ACP::Types::Unstable::MessageMcpNotification
   # @rbs return: void
-  def dispatch(params)
-    notification = ACP::Types::SessionNotification.from_h(params)
-  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError => e
-    @logger.warn("dropped malformed session/update: #{e.class}: #{e.message}")
-  else
-    queue = @lock.synchronize { @streams[notification.session_id]&.push(notification.update) }
-    @updates.call(notification) unless queue
-  end
-
-  # The handler runs on its own thread so a cancelled request is answered
-  # without waiting for it, and whatever it returns after that is pushed to a
-  # queue nobody reads.
-  #
-  # @rbs params: untyped
-  # @rbs return: (ACP::Types::RequestPermissionResponse | ACP::RequestError)
-  def request_permission(params)
-    request = ACP::Types::RequestPermissionRequest.from_h(params)
-  rescue ACP::Types::ParseError => e
-    ACP::RequestError.invalid_params([e.message])
-  rescue KeyError, TypeError, NoMethodError
-    ACP::RequestError.invalid_params
-  else
-    replies = Thread::Queue.new
-    register_permission(request.session_id, replies)
-    Thread.new do
-      # A raised StandardError is not a returned ACP::RequestError, so the two
-      # need distinct shapes on the queue.
-      replies << begin
-        [:value, @permission.call(request)]
-      rescue StandardError => e
-        [:raised, e]
-      end
-    ensure
-      unregister_permission(request.session_id, replies)
-    end
-    settled = replies.pop
-    # Re-raised so the transport's invoke turns it into an error reply, as it
-    # would if the handler ran on the serve thread itself.
-    raise settled[1] if settled[0] == :raise
-
-    settled[1]
+  def mcp_message_notification(notification)
+    @transport.notify('mcp/message', notification.to_h)
   end
 
-  # @rbs session_id: String
-  # @rbs replies: Thread::Queue
-  # @rbs return: void
-  def register_permission(session_id, replies)
-    @lock.synchronize { (@pending_permissions[session_id] ||= []) << replies }
-  end
+  private
 
-  # @rbs session_id: String
-  # @rbs replies: Thread::Queue
-  # @rbs return: void
-  def unregister_permission(session_id, replies)
-    @lock.synchronize do
-      pending = @pending_permissions[session_id]
-      if pending
-        pending.delete(replies)
-        @pending_permissions.delete(session_id) if pending.empty?
-      end
+  # @rbs route: ACP::ClientConnection::Route
+  # @rbs return: ^(untyped) -> (untyped | ACP::RequestError)
+  def serve(route)
+    lambda do |params|
+      next refuse(route) unless route.advertised.call(instance_variable_get(route.family))
+
+      request = route.type.from_h(params)
+    rescue ACP::Types::ParseError => e
+      ACP::RequestError.invalid_params([e.message])
+    rescue KeyError, TypeError, NoMethodError
+      ACP::RequestError.invalid_params
+    else
+      # Safe: connect refuses an advertised capability no handler serves, and
+      # the mcp route is only registered when one is injected.
+      instance_variable_get(route.handler).call(request)
     end
   end
 
-  # The routes are registered at start, before connect records the advertised
-  # capabilities, so each one answers -32601 until then.
-  #
-  # @rbs params: untyped
-  # @rbs return: (ACP::Types::ReadTextFileResponse | ACP::RequestError)
-  def read_text_file(params)
-    return ACP::RequestError.unadvertised('fs.readTextFile') unless @fs_capabilities&.read_text_file
-
-    request = ACP::Types::ReadTextFileRequest.from_h(params)
-  rescue ACP::Types::ParseError => e
-    ACP::RequestError.invalid_params([e.message])
-  rescue KeyError, TypeError, NoMethodError
-    ACP::RequestError.invalid_params
-  else
-    # Safe: connect refuses an advertised capability no handler serves.
-    handler = @read_text_file #: ^(ACP::Types::ReadTextFileRequest) -> (ACP::Types::ReadTextFileResponse | ACP::RequestError)
-    handler.call(request)
+  # @rbs route: ACP::ClientConnection::Route
+  # @rbs return: ACP::RequestError
+  def refuse(route)
+    ACP::RequestError.public_send(route.refuse, route.key)
   end
 
-  # @rbs params: untyped
-  # @rbs return: (ACP::Types::WriteTextFileResponse | ACP::RequestError)
-  def write_text_file(params)
-    return ACP::RequestError.unadvertised('fs.writeTextFile') unless @fs_capabilities&.write_text_file
-
-    request = ACP::Types::WriteTextFileRequest.from_h(params)
-  rescue ACP::Types::ParseError => e
-    ACP::RequestError.invalid_params([e.message])
-  rescue KeyError, TypeError, NoMethodError
-    ACP::RequestError.invalid_params
-  else
-    # Safe: connect refuses an advertised capability no handler serves.
-    handler = @write_text_file #: ^(ACP::Types::WriteTextFileRequest) -> (ACP::Types::WriteTextFileResponse | ACP::RequestError)
-    handler.call(request)
-  end
-
-  # The terminal routes are registered at start, before connect records the
-  # advertised capability, so each one answers -32601 until then.
-  #
-  # @rbs params: untyped
-  # @rbs return: (ACP::Types::CreateTerminalResponse | ACP::RequestError)
-  def create_terminal(params)
-    return ACP::RequestError.unadvertised('terminal') unless @terminal
-
-    request = ACP::Types::CreateTerminalRequest.from_h(params)
-  rescue KeyError, TypeError, NoMethodError
-    ACP::RequestError.invalid_params
-  else
-    # Safe: connect refuses an advertised capability no handler serves.
-    handler = @create_terminal #: ^(ACP::Types::CreateTerminalRequest) -> (ACP::Types::CreateTerminalResponse | ACP::RequestError)
-    handler.call(request)
-  end
+  # @rbs name: String
+  # @rbs family: Symbol
+  # @rbs capabilities: untyped
+  # @rbs return: void
+  def check_served(name, family, capabilities)
+    unserved = SERVE.filter_map do |route|
+      next unless route.family == family
+      next if instance_variable_get(route.handler)
+      next unless route.advertised.call(capabilities)
 
-  # @rbs params: untyped
-  # @rbs return: (ACP::Types::TerminalOutputResponse | ACP::RequestError)
-  def terminal_output(params)
-    return ACP::RequestError.unadvertised('terminal') unless @terminal
+      route.label
+    end
+    return if unserved.empty?
 
-    request = ACP::Types::TerminalOutputRequest.from_h(params)
-  rescue KeyError, TypeError, NoMethodError
-    ACP::RequestError.invalid_params
-  else
-    # Safe: connect refuses an advertised capability no handler serves.
-    handler = @terminal_output #: ^(ACP::Types::TerminalOutputRequest) -> (ACP::Types::TerminalOutputResponse | ACP::RequestError)
-    handler.call(request)
+    raise ArgumentError, "initialize advertises #{name} methods no handler serves: #{unserved.join(', ')}"
   end
 
-  # The handler 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.
+  # The unstable types are referenced while the row is built, so the route can
+  # only be served when the caller opted in with `require 'acp/types/unstable'`.
+  # It is 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.
   #
-  # @rbs params: untyped
-  # @rbs return: (ACP::Types::WaitForTerminalExitResponse | ACP::RequestError)
-  def wait_for_terminal_exit(params)
-    return ACP::RequestError.unadvertised('terminal') unless @terminal
-
-    request = ACP::Types::WaitForTerminalExitRequest.from_h(params)
-  rescue KeyError, TypeError, NoMethodError
-    ACP::RequestError.invalid_params
-  else
-    # Safe: connect refuses an advertised capability no handler serves.
-    handler = @wait_for_terminal_exit #: ^(ACP::Types::WaitForTerminalExitRequest) -> (ACP::Types::WaitForTerminalExitResponse | ACP::RequestError)
-    handler.call(request)
-  end
-
-  # @rbs params: untyped
-  # @rbs return: (ACP::Types::KillTerminalResponse | ACP::RequestError)
-  def kill_terminal(params)
-    return ACP::RequestError.unadvertised('terminal') unless @terminal
-
-    request = ACP::Types::KillTerminalRequest.from_h(params)
-  rescue KeyError, TypeError, NoMethodError
-    ACP::RequestError.invalid_params
-  else
-    # Safe: connect refuses an advertised capability no handler serves.
-    handler = @kill_terminal #: ^(ACP::Types::KillTerminalRequest) -> (ACP::Types::KillTerminalResponse | ACP::RequestError)
-    handler.call(request)
+  # @rbs return: Hash[String, ^(untyped) -> (untyped | ACP::RequestError)]
+  def mcp_requests
+    return {} unless @mcp_message
+    return {} unless ACP::Types.unstable_enabled?
+
+    route = Route.new(
+      wire: 'mcp/message',
+      type: ACP::Types::Unstable::MessageMcpRequest,
+      handler: :@mcp_message,
+      family: :@mcp_advertised,
+      refuse: :unadvertised_agent,
+      key: 'mcpCapabilities.acp'
+    )
+    { 'mcp/message' => serve(route) }
   end
 
-  # @rbs params: untyped
-  # @rbs return: (ACP::Types::ReleaseTerminalResponse | ACP::RequestError)
-  def release_terminal(params)
-    return ACP::RequestError.unadvertised('terminal') unless @terminal
+  # @rbs type: ACP::Transport::_Parser
+  # @rbs result: (Hash[String, untyped] | ACP::RequestError)
+  # @rbs return: untyped
+  def parse(type, result)
+    return result if result.is_a?(ACP::RequestError)
 
-    request = ACP::Types::ReleaseTerminalRequest.from_h(params)
-  rescue KeyError, TypeError, NoMethodError
-    ACP::RequestError.invalid_params
-  else
-    # Safe: connect refuses an advertised capability no handler serves.
-    handler = @release_terminal #: ^(ACP::Types::ReleaseTerminalRequest) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError)
-    handler.call(request)
+    type.from_h(result)
+  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError
+    ACP::RequestError.invalid_response(result)
   end
 
-  # The routes are registered at start, before connect records the advertised
+  # The route is registered at start, before connect records the advertised
   # capabilities, so a request for an unadvertised mode answers -32602.
   #
   # @rbs params: untyped
   # @rbs return: (ACP::Types::CreateElicitationResponse | ACP::RequestError)
   def create_elicitation(params)
     request = ACP::Types::CreateElicitationRequest.from_h(params)
+  rescue ACP::Types::ParseError => e
+    ACP::RequestError.invalid_params([e.message])
   rescue KeyError, TypeError, NoMethodError
     ACP::RequestError.invalid_params
   else
@@ -506,7 +499,7 @@ class ACP::ClientConnection
     when ACP::Types::CreateElicitationRequest::Mode::Url
       return ACP::RequestError.unadvertised_mode('elicitation.url') unless @elicitation_capabilities&.url
 
-      register_elicitation(request.mode.elicitation_id)
+      @streams.register_elicitation(request.mode.elicitation_id)
     else
       return ACP::RequestError.unadvertised_mode("elicitation.#{request.mode['mode']}")
     end
@@ -516,57 +509,6 @@ class ACP::ClientConnection
     handler.call(request)
   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_elicitation(params)
-    notification = ACP::Types::CompleteElicitationNotification.from_h(params)
-  rescue KeyError, TypeError, NoMethodError => e
-    @logger.warn("dropped malformed elicitation/complete: #{e.class}: #{e.message}")
-  else
-    known = @lock.synchronize { @outstanding_elicitations.delete(notification.elicitation_id) }
-    @complete_elicitation&.call(notification) if known
-  end
-
-  # @rbs elicitation_id: String
-  # @rbs return: void
-  def register_elicitation(elicitation_id)
-    @lock.synchronize { @outstanding_elicitations[elicitation_id] = true }
-  end
-
-  # The fs capabilities initialize advertises that no injected handler serves.
-  #
-  # @rbs capabilities: ACP::Types::FileSystemCapabilities?
-  # @rbs return: Array[String]
-  def unserved_fs_methods(capabilities)
-    {
-      'fs.readTextFile' => capabilities&.read_text_file && !@read_text_file,
-      'fs.writeTextFile' => capabilities&.write_text_file && !@write_text_file
-    }.select { |_, unserved| unserved }.keys
-  end
-
-  # The terminal capabilities initialize advertises that no injected handler
-  # serves.
-  #
-  # @rbs capabilities: bool?
-  # @rbs return: Array[String]
-  def unserved_terminal_methods(capabilities)
-    {
-      'terminal.create' => capabilities && !@create_terminal,
-      'terminal.output' => capabilities && !@terminal_output,
-      'terminal.wait_for_exit' => capabilities && !@wait_for_terminal_exit,
-      'terminal.kill' => capabilities && !@kill_terminal,
-      'terminal.release' => capabilities && !@release_terminal
-    }.select { |_, unserved| unserved }.keys
-  end
-
-  # The elicitation capabilities initialize advertises that no injected
-  # handler serves.
-  #
   # @rbs capabilities: ACP::Types::ElicitationCapabilities?
   # @rbs return: Array[String]
   def unserved_elicitation_modes(capabilities)