little_ghost 0.1.0

data/lib/little_ghost/mcp/client.rb

@@ -0,0 +1,396 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "net/http"
+require "uri"
+
+module LittleGhost
+  # MCP lets LittleGhost agents use tools published by Model Context Protocol
+  # servers. Require +little_ghost/mcp+ to load the optional HTTP integration.
+  module MCP
+    # Model Context Protocol version negotiated by Client.
+    PROTOCOL_VERSION = "2025-06-18"
+
+    # HTTPTransport sends MCP JSON-RPC messages over Streamable HTTP. It applies
+    # time and response-size limits and keeps the negotiated MCP session ID.
+    #
+    # === Security and trust
+    #
+    # HTTPS is required by default. +allow_insecure_http+ is only for an
+    # explicitly trusted local development endpoint. Scope caller-supplied
+    # credential headers to the target server. Response bodies and negotiated
+    # session IDs are validated before use.
+    #
+    # One transport instance retains one negotiated MCP session ID and sends it
+    # with later requests. Scope the transport and its Client to one trusted
+    # server and one authenticated principal; never share that pair across
+    # tenants. LittleGhost does not send MCP session-termination DELETE requests,
+    # so configure server-side expiry or manage that lifecycle outside this
+    # transport when the server requires explicit cleanup.
+    class HTTPTransport
+      # Default upper bound for one MCP response body (10 MiB).
+      DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024
+      SESSION_ID_PATTERN = /\A[\x21-\x7e]{1,256}\z/ # :nodoc:
+
+      # Configures time and response-size limits. +signer+, when
+      # supplied, is called with each Net::HTTP request before it is sent.
+      def initialize(url:, headers: {}, timeout: 60, signer: nil, allow_insecure_http: false,
+        max_response_bytes: DEFAULT_MAX_RESPONSE_BYTES)
+        @uri = URI(url)
+        unless %w[http https].include?(@uri.scheme) && @uri.host
+          raise ConfigurationError, "MCP URL must be an HTTP(S) URL"
+        end
+        if @uri.scheme == "http" && !allow_insecure_http
+          raise ConfigurationError, "MCP URL must use HTTPS unless allow_insecure_http is enabled"
+        end
+
+        @headers = headers.transform_keys(&:to_s).freeze
+        @timeout = Float(timeout)
+        raise ArgumentError, "timeout must be positive" unless @timeout.positive?
+
+        @max_response_bytes = Integer(max_response_bytes)
+        raise ArgumentError, "max_response_bytes must be positive" unless @max_response_bytes.positive?
+
+        @signer = signer
+        @session_id = nil
+      end
+
+      # Sends one JSON-RPC payload. A RunContext supplies cancellation and a
+      # deadline; without it the configured timeout applies.
+      def send(payload, context: nil)
+        return perform_send(payload, timeout: @timeout) unless context
+
+        response = nil
+        stream = Support::InterruptibleStream.new(
+          cancellation_token: context.cancellation_token,
+          deadline: context.deadline
+        ) do |emit|
+          emit.call(perform_send(payload, timeout: context.remaining_time(@timeout)))
+        end
+        stream.each { |value| response = value }
+        response
+      end
+
+      private
+
+      def perform_send(payload, timeout:)
+        request = Net::HTTP::Post.new(@uri)
+        @headers.each { |name, value| request[name] = value }
+        request["Accept"] ||= "application/json, text/event-stream"
+        request["Content-Type"] ||= "application/json"
+        request["MCP-Protocol-Version"] ||= PROTOCOL_VERSION
+        request["Mcp-Session-Id"] = @session_id if @session_id
+        request.body = JSON.generate(payload)
+        @signer&.call(request)
+
+        response = nil
+        response_body = +""
+        http(timeout).request(request) do |received|
+          response = received
+          validate_content_length!(received)
+          received.read_body do |chunk|
+            response_body << chunk
+            raise ProtocolError, "MCP response exceeded #{@max_response_bytes} bytes" if response_body.bytesize > @max_response_bytes
+          end
+        end
+        @session_id = validated_session_id(response["Mcp-Session-Id"]) if response["Mcp-Session-Id"]
+        unless response.is_a?(Net::HTTPSuccess) || response.is_a?(Net::HTTPAccepted)
+          raise ProtocolError, "MCP request failed with HTTP #{response.code}"
+        end
+
+        parse(response, response_body, payload[:id])
+      rescue JSON::ParserError => error
+        raise ProtocolError, "MCP returned invalid JSON: #{error.message}"
+      rescue SystemCallError, SocketError, Timeout::Error => error
+        raise ProviderError, "MCP transport failed: #{error.class}"
+      end
+
+      def http(timeout)
+        Net::HTTP.new(@uri.host, @uri.port).tap do |client|
+          client.use_ssl = @uri.scheme == "https"
+          client.open_timeout = timeout
+          client.read_timeout = timeout
+          client.write_timeout = timeout
+        end
+      end
+
+      def parse(response, body, expected_id)
+        return {} if body.empty?
+
+        if response["Content-Type"].to_s.include?("text/event-stream")
+          payloads = body.scan(/^data:\s*(.+)$/).flatten.reject { |data| data == "[DONE]" }
+          raise ProtocolError, "MCP event stream contained no response" if payloads.empty?
+
+          messages = payloads.map { |payload| JSON.parse(payload) }
+          messages.reverse.find { |message| expected_id.nil? || message["id"] == expected_id } || {}
+        else
+          JSON.parse(body)
+        end
+      end
+
+      def validate_content_length!(response)
+        content_length = response["Content-Length"]
+        if content_length && Integer(content_length, exception: false).to_i > @max_response_bytes
+          raise ProtocolError, "MCP response exceeded #{@max_response_bytes} bytes"
+        end
+      end
+
+      def validated_session_id(value)
+        return value if SESSION_ID_PATTERN.match?(value)
+
+        raise ProtocolError, "MCP server returned an invalid session ID"
+      end
+    end
+
+    # Client makes tools from an MCP server available as ordinary LittleGhost
+    # tools. Agents can use a remote capability without learning a second tool
+    # interface.
+    #
+    #   transport = LittleGhost::MCP::HTTPTransport.new(url: "https://mcp.example/rpc")
+    #   client = LittleGhost::MCP::Client.new(transport:, prefix: "docs")
+    #   client.tools.map(&:tool_name) # => ["docs_search", "docs_fetch"]
+    #
+    # Tool names are normalized and checked for collisions. Pagination, tool
+    # count, and response sizes are limited; +rejected_tools+ and
+    # +definition_filter+ can enforce an application allowlist.
+    #
+    # Server definitions and results remain untrusted input. LittleGhost validates
+    # them before creating tools, but applications still decide which servers and
+    # capabilities an agent may use.
+    #
+    # A client and its transport represent one authenticated server session.
+    # Create a separate pair for each principal or trust boundary. Protocol
+    # initialization and subsequent requests through one client are serialized;
+    # do not share its transport with another client.
+    class Client
+      MAX_TOOL_NAME_LENGTH = 64 # :nodoc:
+      ALIAS_DIGEST_LENGTH = 12 # :nodoc:
+      DEFAULT_MAX_TOOLS = 1_000 # :nodoc:
+      DEFAULT_MAX_PAGES = 100 # :nodoc:
+
+      # Uses a transport that responds to +send+.
+      def initialize(
+        transport:,
+        name: "mcp",
+        prefix: nil,
+        rejected_tools: [],
+        definition_filter: nil,
+        max_tools: DEFAULT_MAX_TOOLS,
+        max_pages: DEFAULT_MAX_PAGES
+      )
+        if definition_filter && !definition_filter.respond_to?(:call)
+          raise ArgumentError, "definition_filter must respond to call"
+        end
+
+        @transport = transport
+        @name = String(name)
+        @prefix = prefix&.to_s
+        @rejected_tools = rejected_tools.map(&:to_s).freeze
+        @definition_filter = definition_filter
+        @max_tools = positive_integer(max_tools, :max_tools)
+        @max_pages = positive_integer(max_pages, :max_pages)
+        @request_id = 0
+        @mutex = Mutex.new
+        @initialization_mutex = Mutex.new
+        @source_names_mutex = Mutex.new
+        @source_names = {}
+        @initialized = false
+      end
+
+      # Negotiates the protocol when needed, then provides Tool instances for
+      # the server's current definitions.
+      def tools(context: nil)
+        @initialization_mutex.synchronize do
+          initialize_protocol(context:) unless @initialized
+        end
+        definitions = list_tool_definitions(context:)
+        definitions.filter_map do |definition|
+          source_name = definition_name(definition)
+          next if @rejected_tools.include?(source_name)
+          next if @definition_filter && !@definition_filter.call(definition)
+
+          build_tool(definition)
+        end
+      end
+
+      # Calls an exposed tool and produces text or serialized structured
+      # content. Server-declared errors raise ToolError.
+      def call(name, arguments, context: nil)
+        source_name = @source_names_mutex.synchronize { @source_names.fetch(name.to_s, name.to_s) }
+        result = request("tools/call", {name: source_name, arguments: arguments}, context:)
+        content = serialize_result(result)
+        raise ToolError, content if result["isError"]
+
+        content
+      end
+
+      private
+
+      def initialize_protocol(context:)
+        result = request("initialize", {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: {},
+          clientInfo: {name: "little_ghost", version: LittleGhost::VERSION}
+        }, context:)
+        unless result["protocolVersion"].to_s == PROTOCOL_VERSION
+          raise ProtocolError, "MCP server did not negotiate protocol #{PROTOCOL_VERSION}"
+        end
+
+        notify("notifications/initialized", context:)
+        @initialized = true
+      end
+
+      def request(method, params = {}, context: nil)
+        expected_id, response = @mutex.synchronize do
+          @request_id += 1
+          [@request_id, @transport.send(
+            {jsonrpc: "2.0", id: @request_id, method: method, params: params},
+            context:
+          )]
+        end
+        raise ProtocolError, "MCP response must be an object" unless response.is_a?(Hash)
+        if (error = response["error"])
+          raise ProtocolError, "MCP response error must be an object" unless error.is_a?(Hash)
+
+          message = error["message"].to_s
+          raise ToolError, message.empty? ? "MCP request failed" : message
+        end
+        if response.key?("id") && response["id"] != expected_id
+          raise ProtocolError, "MCP response ID did not match its request"
+        end
+
+        result = response["result"]
+        raise ProtocolError, "MCP response did not include a result object" unless result.is_a?(Hash)
+
+        result
+      end
+
+      def notify(method, params = {}, context: nil)
+        @transport.send({jsonrpc: "2.0", method: method, params: params}, context:)
+      end
+
+      def list_tool_definitions(context:)
+        definitions = []
+        cursor = nil
+        seen_cursors = {}
+        pages = 0
+        loop do
+          pages += 1
+          raise ProtocolError, "MCP tools/list exceeded #{@max_pages} pages" if pages > @max_pages
+
+          result = request("tools/list", cursor ? {cursor: cursor} : {}, context:)
+          tools = result.fetch("tools", [])
+          raise ProtocolError, "MCP tools/list tools must be an array" unless tools.is_a?(Array)
+
+          definitions.concat(tools)
+          raise ProtocolError, "MCP tools/list exceeded #{@max_tools} tools" if definitions.length > @max_tools
+          cursor = result["nextCursor"]
+          break if cursor.nil? || cursor.empty?
+
+          raise ProtocolError, "MCP tools/list repeated a pagination cursor" if seen_cursors[cursor]
+
+          seen_cursors[cursor] = true
+        end
+        definitions
+      end
+
+      def build_tool(definition)
+        client = self
+        source_name = definition_name(definition)
+        exposed_name = safe_name([@prefix, source_name].compact.join("___"))
+        @source_names_mutex.synchronize do
+          existing = @source_names[exposed_name]
+          if existing && existing != source_name
+            raise ConfigurationError, "MCP tools #{existing.inspect} and #{source_name.inspect} map to #{exposed_name.inspect}"
+          end
+          @source_names[exposed_name] = source_name
+        end
+
+        Tool.define(
+          name: exposed_name,
+          description: present_description(definition["description"]),
+          input_schema: definition.fetch("inputSchema", {type: "object"})
+        ) { |input, context:| client.call(exposed_name, input, context:) }
+      end
+
+      def definition_name(definition)
+        raise ProtocolError, "MCP tool definition must be an object" unless definition.is_a?(Hash)
+
+        name = definition["name"]
+        raise ProtocolError, "MCP tool definition must include a name" unless name.is_a?(String) && !name.empty?
+
+        name
+      end
+
+      def safe_name(name)
+        normalized = name.gsub(/[^a-zA-Z0-9_-]/, "_")
+        raise ConfigurationError, "MCP tool name cannot be empty" if normalized.empty?
+        return normalized if normalized.length <= MAX_TOOL_NAME_LENGTH
+
+        digest = Digest::SHA256.hexdigest(normalized)[0, ALIAS_DIGEST_LENGTH]
+        prefix_length = MAX_TOOL_NAME_LENGTH - ALIAS_DIGEST_LENGTH - 1
+        "#{normalized[0, prefix_length]}_#{digest}"
+      end
+
+      def present_description(description)
+        value = description.to_s
+        value.empty? ? "MCP tool from #{@name}" : value
+      end
+
+      def serialize_content(content)
+        text = content.filter_map { |block| block["text"] if block["type"] == "text" }.join("\n")
+        return text unless text.empty?
+
+        JSON.generate(content)
+      end
+
+      def serialize_result(result)
+        return serialize_content(result.fetch("content", [])) unless result.key?("structuredContent")
+
+        structured = result["structuredContent"]
+        raise ProtocolError, "MCP structuredContent must be an object" unless structured.is_a?(Hash)
+
+        payload = {"structuredContent" => structured}
+        content = result.fetch("content", [])
+        payload["content"] = content unless content.empty?
+        JSON.generate(payload)
+      end
+
+      def positive_integer(value, name)
+        integer = Integer(value)
+        raise ArgumentError, "#{name} must be positive" unless integer.positive?
+
+        integer
+      end
+    end
+
+    # SigV4Signer adds AWS Signature Version 4 authentication to MCP requests.
+    # Requires the application-provided +aws-sigv4+ gem and uses its normal AWS
+    # credentials-provider chain unless one is supplied explicitly.
+    class SigV4Signer
+      # Configures signing for +service+ and +region+.
+      def initialize(service:, region:, credentials_provider: nil)
+        require "aws-sigv4"
+        @signer = Aws::Sigv4::Signer.new(
+          service: service,
+          region: region,
+          credentials_provider: credentials_provider
+        )
+      rescue LoadError
+        raise ConfigurationError, "MCP SigV4 signing requires the optional aws-sigv4 gem"
+      end
+
+      # Signs +request+ in place immediately before transport.
+      def call(request)
+        signature = @signer.sign_request(
+          http_method: request.method,
+          url: request.uri,
+          headers: request.to_hash.transform_values { |values| Array(values).join(",") },
+          body: request.body
+        )
+        signature.headers.each { |name, value| request[name] = value }
+      end
+    end
+  end
+end

data/lib/little_ghost/mcp.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Loads LittleGhost's optional Model Context Protocol client. Requiring
+# +little_ghost+ alone does not load its HTTP integration.
+require_relative "mcp/client"

data/lib/little_ghost/message.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "json"
+
+module LittleGhost
+  # A Message carries one participant's contribution to an agent conversation.
+  # Its content can combine text, attachments, tool activity, and model reasoning.
+  #
+  # Content is normalized into {Content}[rdoc-ref:LittleGhost::Content] blocks
+  # held in a frozen Array. Strings become Content::Text blocks, and hashes use
+  # the serialized content shape accepted by Content.normalize. Nested values
+  # supplied by the caller are retained rather than defensively copied.
+  #
+  #   message = LittleGhost::Message.new(role: :user, content: "Hello")
+  #   message.text # => "Hello"
+  class Message
+    # Participant roles accepted by Message.new.
+    ROLES = %i[system developer user assistant tool].freeze
+
+    # Participant role, normalized Content blocks, and application metadata.
+    attr_reader :role, :content, :metadata
+
+    # Creates a frozen message with a supported +role+, normalized +content+, and
+    # application-defined +metadata+. The content Array and metadata Hash are
+    # frozen, but nested caller-owned values are retained.
+    def initialize(role:, content:, metadata: {})
+      @role = role.to_sym
+      raise ArgumentError, "Unsupported message role: #{role.inspect}" unless ROLES.include?(@role)
+
+      blocks = if content.nil?
+        []
+      elsif content.is_a?(Array)
+        content
+      else
+        [content]
+      end
+      @content = blocks.map { |block| Content.normalize(block) }.freeze
+      @metadata = metadata.freeze
+      freeze
+    end
+
+    # Keeps +value+ when it is already a message, or creates a message from a
+    # hash with string or symbol keys.
+    def self.coerce(value)
+      return value if value.is_a?(self)
+
+      hash = value.transform_keys(&:to_sym)
+      new(**hash)
+    end
+
+    # Joins the visible text blocks without including reasoning or tool content.
+    def text
+      content.grep(Content::Text).map(&:text).join
+    end
+
+    # Removes Content::Reasoning blocks, or keeps +self+ when none are
+    # present.
+    def without_reasoning
+      remaining_content = content.reject { |block| block.is_a?(Content::Reasoning) }
+      return self if remaining_content.length == content.length
+
+      self.class.new(role:, content: remaining_content, metadata:)
+    end
+
+    # Produces the JSON-safe message representation.
+    def to_h
+      {"role" => role.to_s, "content" => content.map(&:to_h), "metadata" => metadata}
+    end
+
+    # Encodes #to_h as JSON, forwarding generator +arguments+.
+    def to_json(*arguments)
+      JSON.generate(to_h, *arguments)
+    end
+  end
+end

data/lib/little_ghost/model.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # Model is the configured connection between an agent role and a provider. It
+  # keeps provider choice and defaults out of the agent class that uses them.
+  #
+  # It merges profile settings into every ModelRequest, validates attachment
+  # modalities declared in metadata, lets providers prepare capability-sensitive
+  # requests, and delegates the normalized stream to the provider.
+  class Model
+    IDENTITY_METADATA_KEYS = %w[provider model_id model_role].freeze # :nodoc:
+
+    # Provider object and name, provider model ID, default settings, normalized
+    # metadata, and logical application role.
+    attr_reader :provider, :provider_name, :id, :settings, :metadata, :role
+
+    # Wraps an object that responds to +stream+.
+    def initialize(provider:, provider_name:, id: nil, model: nil, settings: {}, metadata: {}, role: nil)
+      raise ArgumentError, "provider must respond to stream" unless provider.respond_to?(:stream)
+      raise ArgumentError, "provider_name is required" if provider_name.nil? || provider_name.to_s.empty?
+      raise ArgumentError, "model is required" if (id || model).nil? || (id || model).to_s.empty?
+
+      @provider = provider
+      @provider_name = provider_name.to_sym
+      @id = (id || model)&.to_s
+      @settings = settings.to_h.transform_keys(&:to_sym).freeze
+      @role = role&.to_s
+      profile_metadata = metadata.to_h.reject { |key, _value| IDENTITY_METADATA_KEYS.include?(key.to_s) }
+      @metadata = profile_metadata.merge(
+        provider: @provider_name,
+        model_id: @id,
+        model_role: @role
+      ).freeze
+    end
+
+    # Streams +request+ through the configured provider.
+    #
+    # Profile settings are defaults; settings on +request+ take precedence.
+    def stream(request, &block)
+      validate_input_modalities!(request)
+      configured_request = ModelRequest.new(
+        messages: request.messages,
+        tools: request.tools,
+        settings: settings.merge(request.settings),
+        output_schema: request.output_schema,
+        tool_choice: request.tool_choice,
+        required_capabilities: request.required_capabilities,
+        cancellation_token: request.cancellation_token,
+        deadline: request.deadline
+      )
+      if provider.respond_to?(:prepare_request)
+        configured_request = provider.prepare_request(configured_request, capabilities:)
+      end
+      provider.stream(configured_request, &block)
+    end
+
+    # Uses advertised provider capabilities, falling back to the permissive legacy
+    # contract for providers that do not advertise them.
+    def capabilities
+      @capabilities ||= if provider.respond_to?(:capabilities)
+        provider.capabilities(metadata:)
+      else
+        ModelCapabilities.legacy
+      end
+    end
+
+    private
+
+    def validate_input_modalities!(request)
+      supported = metadata[:input_modalities] || metadata["input_modalities"]
+      return unless supported
+
+      required = request.messages.flat_map do |message|
+        message.content.filter_map do |block|
+          case block
+          when Content::Image then "image"
+          when Content::Document then "file"
+          end
+        end
+      end.uniq
+      missing = required - Array(supported).map { |value| value.to_s.downcase }
+      return if missing.empty?
+
+      raise UnsupportedInputError,
+        "The selected model does not support #{missing.join(" and ")} attachments. Choose a compatible model or remove those attachments."
+    end
+  end
+end

data/lib/little_ghost/model_capabilities.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  # ModelCapabilities tells LittleGhost which optional features a model can use.
+  # It keeps structured results and tool selection from relying on provider
+  # guesswork.
+  #
+  # A +nil+ +supported_parameters+ list means parameter support is not restricted.
+  # Use +ModelCapabilities.unknown+ when capability metadata is unavailable and
+  # callers should avoid assuming support.
+  ModelCapabilities = Data.define( # :nodoc:
+    :native_structured_output,
+    :tools,
+    :tool_choice,
+    :supported_parameters,
+    :known
+  ) do
+    # Creates an immutable capability description.
+    def initialize(
+      native_structured_output: false,
+      tools: false,
+      tool_choice: false,
+      supported_parameters: nil,
+      known: true
+    )
+      parameters = supported_parameters&.map(&:to_s)&.uniq&.freeze
+      super(
+        native_structured_output: !!native_structured_output,
+        tools: !!tools,
+        tool_choice: !!tool_choice,
+        supported_parameters: parameters,
+        known: !!known
+      )
+    end
+
+    def native_structured_output? = native_structured_output
+    def tools? = tools
+    def tool_choice? = tool_choice
+    def known? = known
+
+    # Checks whether any supplied parameter name is supported.
+    def supports_parameter?(*names)
+      return true unless supported_parameters
+
+      names.flatten.any? { |name| supported_parameters.include?(name.to_s) }
+    end
+
+    # Supplies the backwards-compatible capability set for legacy providers.
+    def self.legacy
+      new(native_structured_output: true, tools: true, tool_choice: true)
+    end
+
+    # Marks capability support as unknown.
+    def self.unknown
+      new(known: false)
+    end
+  end
+
+  # Describes the optional features a model can use. Providers expose this value
+  # so structured results and tool selection do not rely on provider guesswork.
+  # A +nil+ supported-parameter list means support is unrestricted.
+  class ModelCapabilities < Data # :doc:
+    ##
+    # :singleton-method: new
+    # :call-seq:
+    #   new(native_structured_output: false, tools: false, tool_choice: false,
+    #       supported_parameters: nil, known: true) -> ModelCapabilities
+    #
+    # Normalizes flags to booleans and stores unique parameter-name Strings in a
+    # frozen Array.
+
+    ##
+    # :attr_reader: native_structured_output
+    # Whether the model accepts a provider-native structured-output schema.
+
+    ##
+    # :attr_reader: tools
+    # Whether the model accepts tool definitions.
+
+    ##
+    # :attr_reader: tool_choice
+    # Whether the model accepts an explicit tool-selection policy.
+
+    ##
+    # :attr_reader: supported_parameters
+    # A frozen Array of provider parameter-name Strings, or +nil+ when support is
+    # unrestricted. Caller-supplied Strings may be retained rather than copied.
+
+    ##
+    # :attr_reader: known
+    # Whether this value represents known capability metadata.
+
+    ##
+    # :method: native_structured_output?
+    # Indicates whether provider-native structured output is available.
+
+    ##
+    # :method: tools?
+    # Indicates whether the model accepts tools.
+
+    ##
+    # :method: tool_choice?
+    # Indicates whether the model accepts an explicit tool choice.
+
+    ##
+    # :method: known?
+    # Indicates whether capability metadata is known.
+
+    ##
+    # :method: supports_parameter?
+    # :call-seq:
+    #   supports_parameter?(*names) -> boolean
+    #
+    # Checks whether any supplied parameter name is supported. An unrestricted
+    # capability set supports every name.
+
+    ##
+    # :singleton-method: legacy
+    # Supplies the permissive capability set for providers that predate explicit
+    # capability reporting.
+
+    ##
+    # :singleton-method: unknown
+    # Marks capability support as unknown so callers avoid assuming support.
+  end
+end