acp-sdk 0.12.0 → 0.14.0

data/lib/acp/client_connection/streams.rb

@@ -1,39 +1,31 @@
 # frozen_string_literal: true
 
-# It holds no send facade of its own — requests go through the sender and
-# answers to the agent ride the connection's routes — so it is unit-testable
-# without a transport.
 class ACP::ClientConnection::Streams
   CANCELLED = ACP::Types::RequestPermissionResponse.new(
     outcome: ACP::Types::RequestPermissionOutcome::Cancelled.new
   ) #: ACP::Types::RequestPermissionResponse
 
-  # @rbs @sender: ACP::ClientConnection::Streams::_Sender
+  # @rbs @sender: ACP::Transport::Stdio
   # @rbs @permission: ACP::ClientConnection::_PermissionHandler
   # @rbs @updates: ACP::ClientConnection::_UpdateHandler
-  # @rbs @complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?
   # @rbs @logger: ACP::Transport::_Logger
   # @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 sender: ACP::ClientConnection::Streams::_Sender
+  # @rbs sender: ACP::Transport::Stdio
   # @rbs permission: ACP::ClientConnection::_PermissionHandler
   # @rbs updates: ACP::ClientConnection::_UpdateHandler
   # @rbs logger: ACP::Transport::_Logger
-  # @rbs complete_elicitation: (^(ACP::Types::CompleteElicitationNotification) -> void)?
   # @rbs return: void
-  def initialize(sender:, permission:, updates:, logger:, complete_elicitation: nil)
+  def initialize(sender:, permission:, updates:, logger:)
     @sender = sender
     @permission = permission
     @updates = updates
-    @complete_elicitation = complete_elicitation
     @logger = logger
     @lock = Mutex.new
     @streams = {}
     @pending_permissions = {}
-    @outstanding_elicitations = {}
   end
 
   # The request waits on its own thread so the caller's thread can yield each
@@ -80,12 +72,13 @@ class ACP::ClientConnection::Streams
   # @rbs params: untyped
   # @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
+    notification = ACP::Types.parse(ACP::Types::SessionNotification, params)
+    if notification.is_a?(ACP::Types::ParseError)
+      @logger.warn("dropped malformed session/update: #{notification.message}")
+    else
+      queue = @lock.synchronize { @streams[notification.session_id]&.push(notification.update) }
+      @updates.call(notification) unless queue
+    end
   end
 
   # The handler runs on its own thread so a cancelled request is answered
@@ -95,12 +88,9 @@ class ACP::ClientConnection::Streams
   # @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
+    request = ACP::Types.parse(ACP::Types::RequestPermissionRequest, params)
+    return ACP::RequestError.invalid_params([request.message]) if request.is_a?(ACP::Types::ParseError)
+
     replies = Thread::Queue.new
     register_permission(request.session_id, replies)
     # The handler runs on the transport's serve thread, so the serving
@@ -108,22 +98,22 @@ class ACP::ClientConnection::Streams
     serving = @sender.cancellation
     Thread.new do
       ACP::Transport::Cancellation.current = serving
-      # A raised StandardError is not a returned ACP::RequestError, so the two
-      # need distinct shapes on the queue.
       replies << begin
-        [:value, @permission.call(request)]
+        @permission.call(request)
       rescue StandardError => e
-        [:raised, e]
+        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] == :raised
+    # A handler answers with a response or an ACP::RequestError, neither of
+    # them an exception, so one on the queue was raised. 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 if settled.is_a?(StandardError)
 
-    settled[1]
+    settled
   end
 
   # The spec requires a pending session/request_permission to be answered with
@@ -134,29 +124,7 @@ class ACP::ClientConnection::Streams
   # @rbs return: void
   def cancel(session_id)
     pending = @lock.synchronize { @pending_permissions.delete(session_id) }
-    pending&.each { |replies| replies << [:value, CANCELLED] }
-  end
-
-  # @rbs elicitation_id: String
-  # @rbs return: void
-  def register_elicitation(elicitation_id)
-    @lock.synchronize { @outstanding_elicitations[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_elicitation(params)
-    notification = ACP::Types::CompleteElicitationNotification.from_h(params)
-  rescue ACP::Types::ParseError, 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
+    pending&.each { |replies| replies << CANCELLED }
   end
 
   private

data/lib/acp/client_connection.rb

@@ -1,223 +1,63 @@
 # frozen_string_literal: true
 
 class ACP::ClientConnection
-  # @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))?
-  # @rbs @create_terminal: (^(ACP::Types::CreateTerminalRequest) -> (ACP::Types::CreateTerminalResponse | ACP::RequestError))?
-  # @rbs @terminal_output: (^(ACP::Types::TerminalOutputRequest) -> (ACP::Types::TerminalOutputResponse | ACP::RequestError))?
-  # @rbs @wait_for_terminal_exit: (^(ACP::Types::WaitForTerminalExitRequest) ->
-  #   (ACP::Types::WaitForTerminalExitResponse | ACP::RequestError))?
-  # @rbs @kill_terminal: (^(ACP::Types::KillTerminalRequest) -> (ACP::Types::KillTerminalResponse | ACP::RequestError))?
-  # @rbs @release_terminal: (^(ACP::Types::ReleaseTerminalRequest) -> (ACP::Types::ReleaseTerminalResponse | ACP::RequestError))?
-  # @rbs @elicitation: (^(ACP::Types::CreateElicitationRequest) ->
-  #   (ACP::Types::CreateElicitationResponse | ACP::RequestError))?
-  # @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 @transport: ACP::Transport::Stdio
   # @rbs @streams: ACP::ClientConnection::Streams
-  # @rbs @logger: ACP::Transport::_Logger
+  # @rbs @inbound: ACP::ClientConnection::Inbound
 
   IGNORE = ->(_notification) {} #: ^(ACP::Types::SessionNotification) -> void
 
-  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::Transport::_Transport
+  # @rbs transport: ACP::Transport::Stdio
   # @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))?
-  # @rbs create_terminal: (^(ACP::Types::CreateTerminalRequest) -> (ACP::Types::CreateTerminalResponse | ACP::RequestError))?
-  # @rbs terminal_output: (^(ACP::Types::TerminalOutputRequest) -> (ACP::Types::TerminalOutputResponse | ACP::RequestError))?
-  # @rbs wait_for_terminal_exit: (^(ACP::Types::WaitForTerminalExitRequest) ->
-  #   (ACP::Types::WaitForTerminalExitResponse | ACP::RequestError))?
-  # @rbs kill_terminal: (^(ACP::Types::KillTerminalRequest) -> (ACP::Types::KillTerminalResponse | ACP::RequestError))?
-  # @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 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 streams: ACP::ClientConnection::Streams?
   # @rbs logger: ACP::Transport::_Logger
-  # @rbs return: void
-  def initialize(
+  # @rbs return: ACP::ClientConnection
+  def self.build(
     transport:,
     permission:,
-    read_text_file: nil,
-    write_text_file: nil,
-    create_terminal: nil,
-    terminal_output: nil,
-    wait_for_terminal_exit: nil,
-    kill_terminal: nil,
-    release_terminal: nil,
-    elicitation: nil,
-    complete_elicitation: nil,
     updates: IGNORE,
+    fs: nil, # rubocop:disable Naming/MethodParameterName -- named after ClientCapabilities#fs
+    terminal: nil,
+    elicitation: nil,
     mcp_message: nil,
     extension_requests: {},
     extension_notifications: {},
-    streams: nil,
     logger: ACP::Transport::StderrLogger.new
   )
+    inbound = Inbound.new(
+      elicitations: Elicitations.new(handler: elicitation, logger:),
+      fs:,
+      terminal:,
+      elicitation:,
+      mcp_message:,
+      extension_requests:,
+      extension_notifications:
+    )
+    new(transport:, streams: Streams.new(sender: transport, permission:, updates:, logger:), inbound:)
+  end
+
+  # @rbs transport: ACP::Transport::Stdio
+  # @rbs streams: ACP::ClientConnection::Streams
+  # @rbs inbound: ACP::ClientConnection::Inbound
+  # @rbs return: void
+  def initialize(transport:, streams:, inbound:)
     @transport = transport
-    @read_text_file = read_text_file
-    @write_text_file = write_text_file
-    @create_terminal = create_terminal
-    @terminal_output = terminal_output
-    @wait_for_terminal_exit = wait_for_terminal_exit
-    @kill_terminal = kill_terminal
-    @release_terminal = release_terminal
-    @elicitation = elicitation
-    @mcp_message = mcp_message
-    @mcp_advertised = nil
-    @fs_capabilities = nil
-    @terminal = nil
-    @elicitation_capabilities = nil
-    @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) }
-    @streams = streams || Streams.new(sender: transport, permission:, updates:, logger:, complete_elicitation:)
-    @logger = logger
+    @streams = streams
+    @inbound = inbound
   end
 
   # @rbs return: Thread
   def start
     @transport.start(
-      requests: {
-        'session/request_permission' => @streams.method(:request_permission),
-        'elicitation/create' => method(:create_elicitation)
-      }.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)
+      requests: { 'session/request_permission' => @streams.method(:request_permission), **@inbound.requests },
+      notifications: { 'session/update' => @streams.method(:dispatch), **@inbound.notifications }
     )
   end
 
@@ -227,21 +67,7 @@ class ACP::ClientConnection
   # @rbs request: ACP::Types::InitializeRequest
   # @rbs return: ACP::Types::InitializeResponse | ACP::RequestError
   def connect(request)
-    capabilities = request.client_capabilities
-    fs = capabilities&.fs
-    terminal = capabilities&.terminal
-    check_served('fs', :@fs_capabilities, fs)
-    check_served('terminal', :@terminal, terminal)
-
-    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 = fs
-    @terminal = terminal
-    @elicitation_capabilities = elicitation
+    @inbound.advertise(request.client_capabilities)
     result = @transport.request('initialize', request.to_h)
     response = parse(ACP::Types::InitializeResponse, result)
     return response if response.is_a?(ACP::RequestError)
@@ -249,7 +75,7 @@ class ACP::ClientConnection
     # 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'] || {})
+    @inbound.mcp_advertised = ACP::Protocol.mcp_acp_advertised?(reply['agentCapabilities'] || {})
     return response if response.protocol_version == ACP::Protocol::PROTOCOL_VERSION
 
     ACP::RequestError.unsupported_protocol_version(
@@ -407,114 +233,13 @@ class ACP::ClientConnection
 
   private
 
-  # @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
-
-  # @rbs route: ACP::ClientConnection::Route
-  # @rbs return: ACP::RequestError
-  def refuse(route)
-    ACP::RequestError.public_send(route.refuse, route.key)
-  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)
-
-      route.label
-    end
-    return if unserved.empty?
-
-    raise ArgumentError, "initialize advertises #{name} methods no handler serves: #{unserved.join(', ')}"
-  end
-
-  # 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 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 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)
 
-    type.from_h(result)
-  rescue ACP::Types::ParseError, KeyError, TypeError, NoMethodError
-    ACP::RequestError.invalid_response(result)
-  end
-
-  # 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
-    case request.mode
-    when ACP::Types::CreateElicitationRequest::Mode::Form
-      return ACP::RequestError.unadvertised_mode('elicitation.form') unless @elicitation_capabilities&.form
-    when ACP::Types::CreateElicitationRequest::Mode::Url
-      return ACP::RequestError.unadvertised_mode('elicitation.url') unless @elicitation_capabilities&.url
-
-      @streams.register_elicitation(request.mode.elicitation_id)
-    else
-      return ACP::RequestError.unadvertised_mode("elicitation.#{request.mode['mode']}")
-    end
-
-    # Safe: connect refuses an advertised mode no handler serves.
-    handler = @elicitation #: ^(ACP::Types::CreateElicitationRequest) -> (ACP::Types::CreateElicitationResponse | ACP::RequestError)
-    handler.call(request)
-  end
-
-  # @rbs capabilities: ACP::Types::ElicitationCapabilities?
-  # @rbs return: Array[String]
-  def unserved_elicitation_modes(capabilities)
-    {
-      'elicitation.form' => capabilities&.form && !@elicitation,
-      'elicitation.url' => capabilities&.url && !@elicitation
-    }.select { |_, unserved| unserved }.keys
+    response = ACP::Types.parse(type, result)
+    response.is_a?(ACP::Types::ParseError) ? ACP::RequestError.invalid_response(result) : response
   end
 end

data/lib/acp/extensions.rb

@@ -12,4 +12,10 @@ module ACP::Extensions
 
     raise ArgumentError, "extension method names must start with '_' (got #{name.inspect})"
   end
+
+  # @rbs names: Array[String]
+  # @rbs return: void
+  def validate_names(names)
+    names.each { |name| validate_name(name) }
+  end
 end

data/lib/acp/protocol.rb

@@ -5,6 +5,19 @@ module ACP::Protocol
 
   extend self
 
+  # Readers missing along the chain count as unadvertised, so the stable
+  # capabilities answer false for the unstable-only paths (fork, providers).
+  #
+  # @rbs capabilities: untyped
+  # @rbs path: Array[Symbol]
+  # @rbs return: bool
+  def advertised?(capabilities, path)
+    # reduce's U pins to the argument's type, but the chain walks through
+    # unrelated capability types.
+    value = path.reduce(capabilities) { |node, name| node.respond_to?(name) ? node.public_send(name) : nil } #: untyped
+    value ? true : false
+  end
+
   # @rbs capabilities: (ACP::Types::AgentCapabilities | ACP::Types::Unstable::AgentCapabilities | Hash[String, untyped])
   # @rbs return: bool
   def mcp_acp_advertised?(capabilities)
@@ -21,13 +34,10 @@ module ACP::Protocol
         # mcpCapabilities is re-parsed from the raw hash with the unstable
         # type. Only that sub-object: the other unstable fields arrive
         # unvalidated and must not decide whether MCP is advertised.
-        raw = capabilities['mcpCapabilities']
-        ACP::Types::Unstable::McpCapabilities.from_h(raw) if raw.is_a?(Hash)
+        ACP::Types.parse(ACP::Types::Unstable::McpCapabilities, capabilities['mcpCapabilities'])
       end
     return false unless mcp.is_a?(ACP::Types::Unstable::McpCapabilities)
 
     mcp.acp ? true : false
-  rescue ACP::Types::ParseError
-    false
   end
 end

data/lib/acp/transport/reply.rb

@@ -2,12 +2,12 @@
 
 class ACP::Transport::Reply
   # @dynamic result
-  attr_reader :result #: ACP::Transport::Stdio::_ToH
+  attr_reader :result #: ACP::Transport::_Response
 
   # @dynamic after
   attr_reader :after #: ^() -> void
 
-  # @rbs result: ACP::Transport::Stdio::_ToH
+  # @rbs result: ACP::Transport::_Response
   # @rbs after: ^() -> void
   # @rbs return: void
   def initialize(result, after:)

data/lib/acp/transport/stdio.rb

@@ -245,7 +245,7 @@ class ACP::Transport::Stdio
   #
   # @rbs handler: _Handler
   # @rbs params: untyped
-  # @rbs return: (_ToH | ACP::RequestError | ACP::Transport::Reply)
+  # @rbs return: (ACP::Transport::_Response | ACP::RequestError | ACP::Transport::Reply)
   def invoke(handler, params)
     handler.call(params)
   rescue StandardError => e
@@ -254,7 +254,7 @@ class ACP::Transport::Stdio
   end
 
   # @rbs id: untyped
-  # @rbs outcome: (_ToH | ACP::RequestError)
+  # @rbs outcome: (ACP::Transport::_Response | ACP::RequestError)
   # @rbs return: void
   def reply(id, outcome)
     payload = case outcome

data/lib/acp/types/parse_error.rb

@@ -13,7 +13,7 @@ class ACP::Types::ParseError < StandardError
   def initialize(segments, detail)
     @segments = segments.freeze
     @detail = detail
-    super("#{path}: #{detail}")
+    super(segments.empty? ? detail : "#{path}: #{detail}")
   end
 
   # @dynamic segments

data/lib/acp/types.rb

@@ -9,4 +9,17 @@ module ACP::Types
   def self.unstable_enabled?
     !defined?(ACP::Types::Unstable).nil?
   end
+
+  # Generated from_h checks only nested values, so a payload that is not an
+  # object is rejected here: a String would answer nil for every key and parse
+  # as an empty object.
+  #
+  # @rbs type: ACP::Transport::_Parser
+  # @rbs payload: untyped
+  # @rbs return: untyped
+  def self.parse(type, payload)
+    ACP::Types::Check.object(payload, [], type)
+  rescue ACP::Types::ParseError => e
+    e
+  end
 end

data/lib/acp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ACP
-  VERSION = '0.12.0'
+  VERSION = '0.14.0'
 end

data/sig/generated/acp/agent_connection/client.rbs

@@ -3,15 +3,15 @@
 class ACP::AgentConnection::Client
   @mcp_advertised: bool
 
-  @peer: ACP::Transport::_Peer
+  @peer: ACP::Transport::Stdio
 
   # @dynamic capabilities, capabilities=
   attr_accessor capabilities: ACP::Types::ClientCapabilities?
 
-  # @rbs peer: ACP::Transport::_Peer
+  # @rbs peer: ACP::Transport::Stdio
   # @rbs mcp_advertised: bool
   # @rbs return: void
-  def initialize: (peer: ACP::Transport::_Peer, ?mcp_advertised: bool) -> void
+  def initialize: (peer: ACP::Transport::Stdio, ?mcp_advertised: bool) -> void
 
   # @rbs session_id: String
   # @rbs update: ACP::Types::SessionUpdate::t