acp-sdk 0.9.0 → 0.11.0

data/lib/acp/protocol.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ACP::Protocol
+  PROTOCOL_VERSION = 1 #: Integer
+
+  extend self
+
+  # @rbs capabilities: (ACP::Types::AgentCapabilities | ACP::Types::Unstable::AgentCapabilities | Hash[String, untyped])
+  # @rbs return: bool
+  def mcp_acp_advertised?(capabilities)
+    # The stable McpCapabilities has no acp field, so the gate can only read it
+    # when the caller opted in with `require 'acp/types/unstable'`.
+    return false unless ACP::Types.unstable_enabled?
+
+    mcp =
+      case capabilities
+      when ACP::Types::AgentCapabilities, ACP::Types::Unstable::AgentCapabilities
+        capabilities.mcp_capabilities #: ACP::Types::McpCapabilities | ACP::Types::Unstable::McpCapabilities?
+      when Hash
+        # The client's stable parse of the initialize reply drops acp, so
+        # 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)
+      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/request_error.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
-# The schema's JSON-RPC Error object, named after the official SDKs'
-# RequestError: built by handlers and local refusals, and decoded from a
-# peer's error replies by the transport.
+# Named after the official SDKs' RequestError rather than the schema's Error.
 class ACP::RequestError
   PARSE_ERROR = -32_700 #: Integer
   INVALID_REQUEST = -32_600 #: Integer
@@ -60,9 +58,8 @@ class ACP::RequestError
     new(code: INVALID_PARAMS, message: 'Invalid params', data: errors && { errors: errors })
   end
 
-  # The method-not-found code for a method the client's capabilities do not
-  # advertise, with a message that names the capability so it can be told
-  # apart from an unknown method.
+  # The message names the capability so the refusal can be told apart from an
+  # unknown method, though both use the -32601 code.
   #
   # @rbs capability: String
   # @rbs return: ACP::RequestError
@@ -70,11 +67,9 @@ class ACP::RequestError
     new(code: METHOD_NOT_FOUND, message: "Client does not advertise #{capability}")
   end
 
-  # The invalid-params code for a request whose mode the client's
-  # capabilities do not advertise, with a message that names the mode so it
-  # can be told apart from malformed params. The spec gives elicitation a
-  # mode in its params, so an unadvertised one is invalid params rather than
-  # method not found.
+  # The message names the mode so the refusal can be told apart from malformed
+  # params. The spec gives elicitation a mode in its params, so an unadvertised
+  # one is invalid params rather than method not found.
   #
   # @rbs mode: String
   # @rbs return: ACP::RequestError
@@ -82,6 +77,12 @@ class ACP::RequestError
     new(code: INVALID_PARAMS, message: "Client does not advertise #{mode}")
   end
 
+  # @rbs capability: String
+  # @rbs return: ACP::RequestError
+  def self.unadvertised_agent(capability)
+    new(code: METHOD_NOT_FOUND, message: "Agent does not advertise #{capability}")
+  end
+
   # @rbs return: ACP::RequestError
   def self.internal_error
     new(code: INTERNAL_ERROR, message: 'Internal error')
@@ -96,8 +97,7 @@ class ACP::RequestError
     new(code: INTERNAL_ERROR, message: 'Invalid response', data: response)
   end
 
-  # A local refusal of an initialize reply that names a version the SDK does
-  # not speak; the message names both versions so logs can tell it from a
+  # The message names both versions so logs can tell this local refusal from a
   # peer's error.
   #
   # @rbs requested: Integer

data/lib/acp/transport/cancellation.rb

@@ -1,9 +1,19 @@
 # frozen_string_literal: true
 
-# Whether the peer cancelled one request. The transport creates one per served
-# request, marks it when the peer's $/cancel_request arrives, and hands it to
-# the serving thread, whose handler can observe it and end the request early.
 class ACP::Transport::Cancellation
+  KEY = :acp_serving_cancellation #: Symbol
+
+  # @rbs return: ACP::Transport::Cancellation?
+  def self.current
+    Thread.current[KEY] #: ACP::Transport::Cancellation?
+  end
+
+  # @rbs cancellation: ACP::Transport::Cancellation?
+  # @rbs return: void
+  def self.current=(cancellation)
+    Thread.current[KEY] = cancellation
+  end
+
   # @rbs @lock: Thread::Mutex
   # @rbs @cancelled: bool
 

data/lib/acp/transport/reply.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-# A request handler's outcome plus a callback the transport runs once that
-# outcome is on the wire, for messages the peer must only see after the reply.
 class ACP::Transport::Reply
   # @dynamic result
   attr_reader :result #: ACP::Transport::Stdio::_ToH

data/lib/acp/transport/stderr_logger.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
-# The default sink for dropped messages and swallowed errors: the spec
-# sanctions agents logging to stderr.
+# The spec sanctions agents logging to stderr.
 class ACP::Transport::StderrLogger
   # @rbs message: String
   # @rbs return: void

data/lib/acp/transport/stdio.rb

@@ -2,11 +2,10 @@
 
 require 'json'
 
-# JSON-RPC 2.0 over newline-delimited JSON on an IO pair. A reader thread
-# dispatches inbound messages while outbound requests are pending, and each
-# inbound request is served on its own thread, so a handler can make an
-# outbound request mid-turn and still see notifications (e.g. session/cancel)
-# that arrive meanwhile.
+# A reader thread dispatches inbound messages while outbound requests are
+# pending, and each inbound request is served on its own thread, so a handler
+# can make an outbound request mid-turn and still see notifications (e.g.
+# session/cancel) that arrive meanwhile.
 class ACP::Transport::Stdio
   # @rbs @input: _Reader
   # @rbs @output: _Writer
@@ -22,9 +21,6 @@ class ACP::Transport::Stdio
     code: ACP::RequestError::INTERNAL_ERROR, message: 'Connection closed'
   ) #: ACP::RequestError
 
-  SERVING_CANCEL = :acp_serving_cancellation #: Symbol
-  private_constant :SERVING_CANCEL
-
   # @rbs input: _Reader
   # @rbs output: _Writer
   # @rbs logger: ACP::Transport::_Logger
@@ -41,9 +37,6 @@ class ACP::Transport::Stdio
     @logger = logger
   end
 
-  # Returns the reader thread, which ends at EOF on input after releasing any
-  # pending outbound requests.
-  #
   # @rbs requests: Hash[String, _Handler]
   # @rbs notifications: Hash[String, _NotificationHandler]
   # @rbs return: Thread
@@ -58,14 +51,16 @@ class ACP::Transport::Stdio
 
   # @rbs method: String
   # @rbs params: untyped
-  # @rbs return: (Hash[String, untyped] | ACP::RequestError)
+  # @rbs return: untyped
   def request(method, params = nil)
     queue = Thread::Queue.new
     id = register(queue)
     return CONNECTION_CLOSED unless id
 
     write({ 'jsonrpc' => '2.0', 'id' => id, 'method' => method, 'params' => params }.compact)
-    queue.pop || CONNECTION_CLOSED
+    result = queue.pop
+    # A null result pops nil just as a closed queue does.
+    queue.closed? ? CONNECTION_CLOSED : result
   end
 
   # @rbs method: String
@@ -85,14 +80,17 @@ class ACP::Transport::Stdio
     notify('$/cancel_request', { 'requestId' => id }) if pending
   end
 
-  # The cancellation of the request the calling thread is serving, or nil off
-  # a serve thread. A handler observes the peer's $/cancel_request through it
-  # and can end early with ACP::RequestError.request_cancelled; whatever it
-  # returns, the transport sends exactly one response.
+  # Each id is re-checked against the pending table, so one that settled
+  # between the snapshot and its cancel is not cancelled.
   #
+  # @rbs return: void
+  def cancel_requests
+    @lock.synchronize { @pending.keys }.each { |id| cancel(id) }
+  end
+
   # @rbs return: ACP::Transport::Cancellation?
   def cancellation
-    Thread.current[SERVING_CANCEL] #: ACP::Transport::Cancellation?
+    ACP::Transport::Cancellation.current
   end
 
   private
@@ -132,8 +130,12 @@ class ACP::Transport::Stdio
     elsif error.is_a?(Hash) && error['code'].is_a?(Integer) && error['message'].is_a?(String)
       code, text, data = error.values_at('code', 'message', 'data')
       settle(message['id'], ACP::RequestError.new(code:, message: text, data:))
-    else
+    elsif message.key?('method')
       reply(detectable_id(message), ACP::RequestError.invalid_request)
+    elsif !settle(message['id'], ACP::RequestError.invalid_response(message))
+      # JSON-RPC responses only answer requests, so a malformed one is never
+      # replied to: the error could settle an unrelated request on the peer.
+      @logger.warn('dropped malformed response: no pending request for its id')
     end
   end
 
@@ -167,7 +169,7 @@ class ACP::Transport::Stdio
   def serve(handler, id, params, method)
     cancellation = register_serving(id)
     Thread.new do
-      Thread.current[SERVING_CANCEL] = cancellation
+      ACP::Transport::Cancellation.current = cancellation
       outcome = handler ? invoke(handler, params) : ACP::RequestError.method_not_found(method)
       case outcome
       when ACP::Transport::Reply
@@ -241,9 +243,6 @@ class ACP::Transport::Stdio
     ACP::RequestError.internal_error
   end
 
-  # The success arm is whatever the handler returned, which the transport only
-  # knows serializes with to_h; RequestError picks the error arm of the reply.
-  #
   # @rbs id: untyped
   # @rbs outcome: (_ToH | ACP::RequestError)
   # @rbs return: void
@@ -268,10 +267,10 @@ class ACP::Transport::Stdio
   end
 
   # @rbs id: untyped
-  # @rbs result: (Hash[String, untyped] | ACP::RequestError)
-  # @rbs return: void
+  # @rbs result: untyped
+  # @rbs return: Thread::Queue?
   def settle(id, result)
-    @lock.synchronize { @pending.delete(id) }&.push(result)
+    @lock.synchronize { @pending.delete(id) }&.tap { |queue| queue.push(result) }
   end
 
   # @rbs return: void

data/lib/acp/types/audio_content.rb

@@ -2,50 +2,7 @@
 
 # Generated by bin/types from schema/schema.json. Do not edit.
 
-class ACP::Types::AudioContent
-  # @dynamic annotations
-  attr_reader :annotations #: ACP::Types::Annotations?
+# @rbs!
+#   class ACP::Types::AudioContent = ACP::Types::ContentBlock::Audio
 
-  # @dynamic data
-  attr_reader :data #: String
-
-  # @dynamic mime_type
-  attr_reader :mime_type #: String
-
-  # @dynamic meta
-  attr_reader :meta #: Hash[String, untyped]?
-
-  # @rbs annotations: ACP::Types::Annotations?
-  # @rbs data: String
-  # @rbs mime_type: String
-  # @rbs meta: Hash[String, untyped]?
-  # @rbs return: void
-  def initialize(data:, mime_type:, annotations: nil, meta: nil)
-    @annotations = annotations
-    @data = data
-    @mime_type = mime_type
-    @meta = meta
-    freeze
-  end
-
-  # @rbs hash: Hash[String, untyped]
-  # @rbs return: ACP::Types::AudioContent
-  def self.from_h(hash)
-    new(
-      annotations: ACP::Types::Check.object(
-        hash['annotations'],
-        'annotations',
-        ACP::Types::Annotations,
-        allow_nil: true
-      ),
-      data: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'data'), 'data'),
-      mime_type: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'mimeType'), 'mimeType'),
-      meta: hash['_meta']
-    )
-  end
-
-  # @rbs return: Hash[String, untyped]
-  def to_h
-    { 'data' => data, 'mimeType' => mime_type, 'annotations' => annotations&.to_h, '_meta' => meta }.compact
-  end
-end
+ACP::Types::AudioContent = ACP::Types::ContentBlock::Audio

data/lib/acp/types/auth_method_terminal.rb

@@ -2,63 +2,7 @@
 
 # Generated by bin/types from schema/schema.json. Do not edit.
 
-class ACP::Types::AuthMethodTerminal
-  # @dynamic id
-  attr_reader :id #: String
+# @rbs!
+#   class ACP::Types::AuthMethodTerminal = ACP::Types::AuthMethod::Terminal
 
-  # @dynamic name
-  attr_reader :name #: String
-
-  # @dynamic description
-  attr_reader :description #: String?
-
-  # @dynamic args
-  attr_reader :args #: Array[String]?
-
-  # @dynamic env
-  attr_reader :env #: Hash[String, String]?
-
-  # @dynamic meta
-  attr_reader :meta #: Hash[String, untyped]?
-
-  # @rbs id: String
-  # @rbs name: String
-  # @rbs description: String?
-  # @rbs args: Array[String]?
-  # @rbs env: Hash[String, String]?
-  # @rbs meta: Hash[String, untyped]?
-  # @rbs return: void
-  def initialize(id:, name:, description: nil, args: nil, env: nil, meta: nil)
-    @id = id
-    @name = name
-    @description = description
-    @args = args
-    @env = env
-    @meta = meta
-    freeze
-  end
-
-  # @rbs hash: Hash[String, untyped]
-  # @rbs return: ACP::Types::AuthMethodTerminal
-  def self.from_h(hash)
-    args = ACP::Types::Check.array(hash['args'], 'args', allow_nil: true) do |item, path|
-      ACP::Types::Check.string(item, path)
-    end
-    env = ACP::Types::Check.hash(hash['env'], 'env', allow_nil: true) do |value, path|
-      ACP::Types::Check.string(value, path)
-    end
-    new(
-      id: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'id'), 'id'),
-      name: ACP::Types::Check.string(ACP::Types::Check.key(hash, 'name'), 'name'),
-      description: ACP::Types::Check.string(hash['description'], 'description', allow_nil: true),
-      args:,
-      env:,
-      meta: hash['_meta']
-    )
-  end
-
-  # @rbs return: Hash[String, untyped]
-  def to_h
-    { 'id' => id, 'name' => name, 'description' => description, 'args' => args, 'env' => env, '_meta' => meta }.compact
-  end
-end
+ACP::Types::AuthMethodTerminal = ACP::Types::AuthMethod::Terminal

data/lib/acp/types/available_commands_update.rb

@@ -2,36 +2,7 @@
 
 # Generated by bin/types from schema/schema.json. Do not edit.
 
-class ACP::Types::AvailableCommandsUpdate
-  # @dynamic available_commands
-  attr_reader :available_commands #: Array[ACP::Types::AvailableCommand]
+# @rbs!
+#   class ACP::Types::AvailableCommandsUpdate = ACP::Types::SessionUpdate::AvailableCommandsUpdate
 
-  # @dynamic meta
-  attr_reader :meta #: Hash[String, untyped]?
-
-  # @rbs available_commands: Array[ACP::Types::AvailableCommand]
-  # @rbs meta: Hash[String, untyped]?
-  # @rbs return: void
-  def initialize(available_commands:, meta: nil)
-    @available_commands = available_commands
-    @meta = meta
-    freeze
-  end
-
-  # @rbs hash: Hash[String, untyped]
-  # @rbs return: ACP::Types::AvailableCommandsUpdate
-  def self.from_h(hash)
-    available_commands = ACP::Types::Check.array(
-      ACP::Types::Check.key(hash, 'availableCommands'),
-      'availableCommands'
-    ) do |item, path|
-      ACP::Types::Check.object(item, path, ACP::Types::AvailableCommand)
-    end
-    new(available_commands:, meta: hash['_meta'])
-  end
-
-  # @rbs return: Hash[String, untyped]
-  def to_h
-    { 'availableCommands' => available_commands.map(&:to_h), '_meta' => meta }.compact
-  end
-end
+ACP::Types::AvailableCommandsUpdate = ACP::Types::SessionUpdate::AvailableCommandsUpdate

data/lib/acp/types/boolean_property_schema.rb

@@ -2,45 +2,7 @@
 
 # Generated by bin/types from schema/schema.json. Do not edit.
 
-class ACP::Types::BooleanPropertySchema
-  # @dynamic title
-  attr_reader :title #: String?
+# @rbs!
+#   class ACP::Types::BooleanPropertySchema = ACP::Types::ElicitationPropertySchema::BooleanPropertySchema
 
-  # @dynamic description
-  attr_reader :description #: String?
-
-  # @dynamic default
-  attr_reader :default #: bool?
-
-  # @dynamic meta
-  attr_reader :meta #: Hash[String, untyped]?
-
-  # @rbs title: String?
-  # @rbs description: String?
-  # @rbs default: bool?
-  # @rbs meta: Hash[String, untyped]?
-  # @rbs return: void
-  def initialize(title: nil, description: nil, default: nil, meta: nil)
-    @title = title
-    @description = description
-    @default = default
-    @meta = meta
-    freeze
-  end
-
-  # @rbs hash: Hash[String, untyped]
-  # @rbs return: ACP::Types::BooleanPropertySchema
-  def self.from_h(hash)
-    new(
-      title: ACP::Types::Check.string(hash['title'], 'title', allow_nil: true),
-      description: ACP::Types::Check.string(hash['description'], 'description', allow_nil: true),
-      default: ACP::Types::Check.boolean(hash['default'], 'default', allow_nil: true),
-      meta: hash['_meta']
-    )
-  end
-
-  # @rbs return: Hash[String, untyped]
-  def to_h
-    { 'title' => title, 'description' => description, 'default' => default, '_meta' => meta }.compact
-  end
-end
+ACP::Types::BooleanPropertySchema = ACP::Types::ElicitationPropertySchema::BooleanPropertySchema

data/lib/acp/types/check.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+# Hand-authored support for the generated types: the generator neither emits
+# nor deletes this file (see TypeGenerator::SUPPORT_FILES).
+
+module ACP::Types::Check
+  # @rbs hash: Hash[String, untyped]
+  # @rbs key: String
+  # @rbs return: untyped
+  def self.key(hash, key)
+    hash.fetch(key)
+  rescue KeyError
+    raise ACP::Types::ParseError.new([key], 'is required')
+  end
+
+  # @rbs value: untyped
+  # @rbs path: String | Array[String | Integer]
+  # @rbs allow_nil: bool
+  # @rbs allow_unset: bool
+  # @rbs return: untyped
+  def self.string(value, path, allow_nil: false, allow_unset: false)
+    return value if value.is_a?(String) || skipped?(value, allow_nil, allow_unset)
+
+    raise ACP::Types::ParseError.new(segments(path), "expected String, got #{describe(value)}")
+  end
+
+  # @rbs value: untyped
+  # @rbs path: String | Array[String | Integer]
+  # @rbs allow_nil: bool
+  # @rbs allow_unset: bool
+  # @rbs return: untyped
+  def self.boolean(value, path, allow_nil: false, allow_unset: false)
+    return value if value == true || value == false || skipped?(value, allow_nil, allow_unset)
+
+    raise ACP::Types::ParseError.new(segments(path), "expected boolean, got #{describe(value)}")
+  end
+
+  # @rbs value: untyped
+  # @rbs path: String | Array[String | Integer]
+  # @rbs min: Integer?
+  # @rbs max: Integer?
+  # @rbs allow_nil: bool
+  # @rbs allow_unset: bool
+  # @rbs return: untyped
+  def self.integer(value, path, min: nil, max: nil, allow_nil: false, allow_unset: false)
+    return value if (value.is_a?(Integer) && within?(value, min, max)) || skipped?(value, allow_nil, allow_unset)
+
+    raise ACP::Types::ParseError.new(segments(path), "expected #{bounded('Integer', min, max)}, got #{describe(value)}")
+  end
+
+  # @rbs value: untyped
+  # @rbs path: String | Array[String | Integer]
+  # @rbs min: Integer?
+  # @rbs max: Integer?
+  # @rbs allow_nil: bool
+  # @rbs allow_unset: bool
+  # @rbs return: untyped
+  def self.number(value, path, min: nil, max: nil, allow_nil: false, allow_unset: false)
+    return value if (value.is_a?(Numeric) && within?(value, min, max)) || skipped?(value, allow_nil, allow_unset)
+
+    raise ACP::Types::ParseError.new(segments(path), "expected #{bounded('Numeric', min, max)}, got #{describe(value)}")
+  end
+
+  # @rbs value: untyped
+  # @rbs path: String | Array[String | Integer]
+  # @rbs values: Array[untyped]
+  # @rbs allow_nil: bool
+  # @rbs allow_unset: bool
+  # @rbs return: untyped
+  def self.enum(value, path, values, allow_nil: false, allow_unset: false)
+    return value if values.include?(value) || skipped?(value, allow_nil, allow_unset)
+
+    expected = values.map(&:inspect).join(', ')
+    raise ACP::Types::ParseError.new(segments(path), "expected one of #{expected}, got #{describe(value)}")
+  end
+
+  # @rbs value: untyped
+  # @rbs path: String | Array[String | Integer]
+  # @rbs classes: Array[untyped]
+  # @rbs allow_nil: bool
+  # @rbs allow_unset: bool
+  # @rbs ?&items: (untyped, Array[String | Integer]) -> void
+  # @rbs return: untyped
+  def self.one_of(value, path, classes, allow_nil: false, allow_unset: false, &items)
+    return value if skipped?(value, allow_nil, allow_unset)
+
+    unless classes.any? { |klass| value.is_a?(klass) }
+      expected = classes.map(&:name).join(' | ')
+      raise ACP::Types::ParseError.new(segments(path), "expected #{expected}, got #{describe(value)}")
+    end
+
+    return value unless value.is_a?(Array) && items
+
+    value.each_with_index { |item, index| yield(item, [*segments(path), index]) }
+    value
+  end
+
+  # @rbs value: untyped
+  # @rbs path: String | Array[String | Integer]
+  # @rbs allow_nil: bool
+  # @rbs allow_unset: bool
+  # @rbs &check: (untyped, Array[String | Integer]) -> void
+  # @rbs return: untyped
+  def self.hash(value, path, allow_nil: false, allow_unset: false, &check)
+    return value if skipped?(value, allow_nil, allow_unset)
+    raise ACP::Types::ParseError.new(segments(path), "expected object, got #{describe(value)}") unless value.is_a?(Hash)
+
+    parsed = {} #: Hash[String, untyped]
+    value.each { |key, item| parsed[key] = yield(item, [*segments(path), key]) }
+    parsed
+  end
+
+  # @rbs value: untyped
+  # @rbs path: String | Array[String | Integer]
+  # @rbs allow_nil: bool
+  # @rbs allow_unset: bool
+  # @rbs &check: (untyped, Array[String | Integer]) -> void
+  # @rbs return: untyped
+  def self.array(value, path, allow_nil: false, allow_unset: false, &check)
+    return value if skipped?(value, allow_nil, allow_unset)
+    raise ACP::Types::ParseError.new(segments(path), "expected array, got #{describe(value)}") unless value.is_a?(Array)
+
+    value.each_with_index.map { |item, index| yield(item, [*segments(path), index]) }
+  end
+
+  # @rbs value: untyped
+  # @rbs path: String | Array[String | Integer]
+  # @rbs klass: untyped
+  # @rbs allow_nil: bool
+  # @rbs allow_unset: bool
+  # @rbs return: untyped
+  def self.object(value, path, klass, allow_nil: false, allow_unset: false)
+    return value if skipped?(value, allow_nil, allow_unset)
+    raise ACP::Types::ParseError.new(segments(path), "expected object, got #{describe(value)}") unless value.is_a?(Hash)
+
+    begin
+      klass.from_h(value)
+    rescue ACP::Types::ParseError => e
+      raise e.prefix(*segments(path))
+    end
+  end
+
+  # @rbs value: untyped
+  # @rbs path: String | Array[String | Integer]
+  # @rbs klass: untyped
+  # @rbs allow_nil: bool
+  # @rbs allow_unset: bool
+  # @rbs return: untyped
+  def self.objects(value, path, klass, allow_nil: false, allow_unset: false)
+    return value if skipped?(value, allow_nil, allow_unset)
+    raise ACP::Types::ParseError.new(segments(path), "expected array, got #{describe(value)}") unless value.is_a?(Array)
+
+    value.each_with_index do |item, index|
+      next if item.is_a?(Hash)
+
+      raise ACP::Types::ParseError.new([*segments(path), index], "expected object, got #{describe(item)}")
+    end
+
+    begin
+      klass.from_a(value)
+    rescue ACP::Types::ParseError => e
+      raise e.prefix(*segments(path))
+    end
+  end
+
+  # @rbs value: untyped
+  # @rbs allow_nil: bool
+  # @rbs allow_unset: bool
+  # @rbs return: bool
+  def self.skipped?(value, allow_nil, allow_unset)
+    (value.nil? && allow_nil) || (allow_unset && value.equal?(:unset))
+  end
+
+  # @rbs path: String | Array[String | Integer]
+  # @rbs return: Array[String | Integer]
+  def self.segments(path)
+    path.is_a?(Array) ? path : [path]
+  end
+
+  # @rbs value: untyped
+  # @rbs return: String
+  def self.describe(value)
+    case value
+    when nil then 'null'
+    when true then 'true'
+    when false then 'false'
+    else value.class.name
+    end
+  end
+
+  # @rbs value: Numeric
+  # @rbs min: Integer?
+  # @rbs max: Integer?
+  # @rbs return: bool
+  def self.within?(value, min, max)
+    (min.nil? || value >= min) && (max.nil? || value <= max)
+  end
+
+  # @rbs name: String
+  # @rbs min: Integer?
+  # @rbs max: Integer?
+  # @rbs return: String
+  def self.bounded(name, min, max)
+    if min && max then "#{name} between #{min} and #{max}"
+    elsif min then "#{name} >= #{min}"
+    elsif max then "#{name} <= #{max}"
+    else name
+    end
+  end
+end