agent-client-protocol 0.1.0

data/lib/agent_client_protocol/types/base.rb

@@ -0,0 +1,314 @@
+# frozen_string_literal: true
+require "json"
+require "set"
+
+module AgentClientProtocol
+  module Types
+    class Base
+      class << self
+        attr_reader :definition_name, :schema, :properties, :required_keys, :ruby_property_map, :ruby_to_json_property_map,
+                    :additional_properties, :property_schemas, :unstable
+
+        def configure(definition_name:, schema:, unstable: false)
+          @definition_name = definition_name
+          @schema = schema
+          @unstable = unstable
+
+          @properties = (schema["properties"] || {}).keys.freeze
+          @property_schemas = (schema["properties"] || {}).freeze
+          @required_keys = (schema["required"] || []).freeze
+          @additional_properties = schema["additionalProperties"]
+          @ruby_property_map = build_ruby_property_map(@properties)
+          @ruby_to_json_property_map = @ruby_property_map.each_with_object({}) do |(json_key, ruby_key), acc|
+            acc[ruby_key.to_s] = json_key
+          end.freeze
+
+          define_property_readers!
+          freeze
+        end
+
+        def coerce(value)
+          return value if value.is_a?(self)
+
+          new(value)
+        end
+
+        def build(attributes = nil, **kwargs)
+          if attributes && !kwargs.empty?
+            raise ArgumentError, "pass either attributes Hash or keyword args, not both"
+          end
+
+          payload = attributes || kwargs
+          new(payload)
+        end
+
+        private
+
+        def build_ruby_property_map(property_names)
+          reserved = instance_methods.map(&:to_s).to_set
+          mapping = {}
+
+          property_names.each do |json_key|
+            candidate = ruby_identifier_for(json_key)
+            candidate = "field" if candidate.empty?
+            candidate = "_#{candidate}" if candidate.match?(/\A\d/)
+
+            while reserved.include?(candidate)
+              candidate = "#{candidate}_field"
+            end
+
+            reserved.add(candidate)
+            mapping[json_key] = candidate.to_sym
+          end
+
+          mapping.freeze
+        end
+
+        def ruby_identifier_for(json_key)
+          sanitized = json_key.to_s.sub(/\A_+/, "")
+          step_one = sanitized.gsub(/([A-Z\d]+)([A-Z][a-z])/, '\1_\2')
+          step_two = step_one.gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          step_two.tr("-", "_").downcase
+        end
+
+        def define_property_readers!
+          @ruby_property_map.each do |json_key, ruby_key|
+            next if method_defined?(ruby_key)
+
+            define_method(ruby_key) do
+              @attributes[json_key]
+            end
+          end
+        end
+      end
+
+      def initialize(attributes = nil)
+        unless attributes.nil? || attributes.is_a?(Hash)
+          raise ArgumentError, "#{self.class.definition_name} expects a Hash payload"
+        end
+
+        attributes ||= {}
+        normalized = normalize_attributes(attributes)
+
+        missing = self.class.required_keys.reject { |key| normalized.key?(key) }
+        unless missing.empty?
+          raise ::AgentClientProtocol::Error.invalid_params(
+            "#{self.class.definition_name} missing required keys: #{missing.join(', ')}"
+          )
+        end
+
+        if self.class.additional_properties == false
+          unknown_keys = normalized.keys - self.class.properties
+          unless unknown_keys.empty?
+            raise ::AgentClientProtocol::Error.invalid_params(
+              "#{self.class.definition_name} unknown keys: #{unknown_keys.join(', ')}"
+            )
+          end
+        end
+
+        @attributes = normalized.freeze
+        freeze
+      end
+
+      def [](key)
+        json_key = self.class.ruby_to_json_property_map[key.to_s] || key.to_s
+        @attributes[json_key]
+      end
+
+      def fetch(key, *args)
+        json_key = self.class.ruby_to_json_property_map[key.to_s] || key.to_s
+        @attributes.fetch(json_key, *args)
+      end
+
+      def key?(key)
+        json_key = self.class.ruby_to_json_property_map[key.to_s] || key.to_s
+        @attributes.key?(json_key)
+      end
+
+      def to_h
+        deep_to_h(@attributes)
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.to_h == to_h
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, @attributes].hash
+      end
+
+      private
+
+      def normalize_attributes(attributes)
+        attributes.each_with_object({}) do |(k, v), acc|
+          key = normalize_input_key(k)
+          schema = self.class.property_schemas[key]
+          acc[key] = normalize_input_value(v, schema)
+        end
+      end
+
+      def normalize_input_key(key)
+        key_str = key.to_s
+        return key_str if self.class.properties.include?(key_str)
+
+        self.class.ruby_to_json_property_map[key_str] || key_str
+      end
+
+      def normalize_input_value(value, schema = nil)
+        return self.class.coerce_for_schema(value, schema, unstable: self.class.unstable) unless schema.nil?
+
+        if value.is_a?(Base) || value.is_a?(Scalar)
+          value
+        elsif value.is_a?(Hash)
+          value.transform_keys(&:to_s).transform_values { |nested| normalize_input_value(nested) }
+        elsif value.is_a?(Array)
+          value.map { |item| normalize_input_value(item) }
+        else
+          value
+        end
+      end
+
+      def deep_to_h(value)
+        case value
+        when Base
+          value.to_h
+        when Scalar
+          value.to_h
+        when Hash
+          value.each_with_object({}) do |(k, v), acc|
+            acc[k] = deep_to_h(v)
+          end
+        when Array
+          value.map { |item| deep_to_h(item) }
+        else
+          value
+        end
+      end
+
+      class << self
+        def coerce_for_schema(value, schema, unstable:)
+          return value if schema.nil?
+
+          if schema["$ref"]
+            return coerce_ref(value, schema["$ref"], unstable: unstable)
+          end
+
+          if schema["type"] == "array" && value.is_a?(Array)
+            item_schema = schema["items"]
+            return value.map { |item| coerce_for_schema(item, item_schema, unstable: unstable) }
+          end
+
+          if schema["type"] == "object" && value.is_a?(Hash)
+            inline_properties = schema["properties"] || {}
+            normalized = value.transform_keys(&:to_s)
+            return normalized.each_with_object({}) do |(k, v), acc|
+              acc[k] = coerce_for_schema(v, inline_properties[k], unstable: unstable)
+            end
+          end
+
+          if schema["anyOf"].is_a?(Array)
+            return coerce_union(value, schema["anyOf"], unstable: unstable)
+          end
+
+          if schema["oneOf"].is_a?(Array)
+            return coerce_union(value, schema["oneOf"], unstable: unstable)
+          end
+
+          if schema["allOf"].is_a?(Array)
+            return schema["allOf"].reduce(value) do |memo, sub_schema|
+              coerce_for_schema(memo, sub_schema, unstable: unstable)
+            end
+          end
+
+          value
+        end
+
+        private
+
+        def coerce_ref(value, ref, unstable:)
+          definition_name = parse_ref_definition(ref)
+          return value if definition_name.nil?
+
+          klass = ::AgentClientProtocol::TypeRegistry.fetch(definition_name, unstable: unstable)
+          return value if klass.nil?
+
+          klass.coerce(value)
+        end
+
+        def coerce_union(value, schemas, unstable:)
+          return nil if value.nil? && schemas.any? { |s| s["type"] == "null" }
+
+          schemas.each do |sub_schema|
+            next if sub_schema["type"] == "null"
+
+            coerced = coerce_for_schema(value, sub_schema, unstable: unstable)
+            return coerced unless coerced.equal?(value)
+          rescue StandardError
+            next
+          end
+
+          value
+        end
+
+        def parse_ref_definition(ref)
+          match = ref.match(%r{\A#/\$defs/([^/]+)\z})
+          return nil if match.nil?
+
+          match[1]
+        end
+      end
+    end
+
+    class Scalar
+      class << self
+        attr_reader :definition_name, :schema, :unstable, :coercer
+
+        def configure(definition_name:, schema:, unstable: false, coercer: nil)
+          @definition_name = definition_name
+          @schema = schema
+          @unstable = unstable
+          @coercer = coercer
+          freeze
+        end
+
+        def coerce(value)
+          return value if value.is_a?(self)
+
+          normalized = coercer.nil? ? value : coercer.call(value)
+          new(normalized)
+        end
+      end
+
+      attr_reader :value
+
+      def initialize(value)
+        @value = value
+        freeze
+      end
+
+      def to_h
+        value
+      end
+
+      def to_json(*args)
+        value.to_json(*args)
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && other.value == value
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, value].hash
+      end
+    end
+  end
+end

data/lib/agent_client_protocol/types.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require_relative "types/base"
+
+module AgentClientProtocol
+  module Types
+  end
+end

data/lib/agent_client_protocol/validator.rb

@@ -0,0 +1,300 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  class Validator
+    class ValidationError < StandardError
+      attr_reader :path
+
+      def initialize(path, message)
+        @path = path
+        super(message)
+      end
+    end
+
+    class << self
+      def validate(definition_name, payload, unstable: false)
+        definitions = SchemaRegistry.defs(unstable: unstable)
+        definition_key = definition_name.to_s
+        schema = definitions.fetch(definition_key) do
+          raise ValidationError.new("$", "unknown schema definition #{definition_key}")
+        end
+
+        validate_schema(schema, payload, definitions, "$")
+        true
+      rescue ValidationError => e
+        raise Error.invalid_params("invalid payload for #{definition_name} at #{e.path}: #{e.message}")
+      end
+
+      private
+
+      def validate_schema(schema, value, definitions, path)
+        return if schema.nil? || schema == true
+        raise ValidationError.new(path, "value is not allowed") if schema == false
+        raise ValidationError.new(path, "invalid schema node") unless schema.is_a?(Hash)
+
+        if (ref = schema["$ref"])
+          validate_schema(resolve_ref(ref, definitions, path), value, definitions, path)
+        end
+
+        return if protocol_version_legacy_string?(schema, value, definitions)
+
+        validate_type(schema["type"], value, path) if schema.key?("type")
+        validate_format(schema["format"], value, path) if schema.key?("format")
+        validate_enum(schema["enum"], value, path) if schema.key?("enum")
+        validate_const(schema["const"], value, path) if schema.key?("const")
+        validate_numeric_bounds(schema, value, path)
+        validate_string_bounds(schema, value, path)
+        validate_array_bounds(schema, value, path)
+
+        validate_object(schema, value, definitions, path)
+        validate_items(schema["items"], value, definitions, path) if schema.key?("items")
+
+        validate_all_of(schema["allOf"], value, definitions, path) if schema["allOf"].is_a?(Array)
+        validate_any_of(schema["anyOf"], value, definitions, path) if schema["anyOf"].is_a?(Array)
+        validate_one_of(schema["oneOf"], value, definitions, path) if schema["oneOf"].is_a?(Array)
+      end
+
+      def resolve_ref(ref, definitions, path)
+        match = ref.to_s.match(%r{\A#/\$defs/([^/]+)\z})
+        raise ValidationError.new(path, "unsupported $ref #{ref.inspect}") if match.nil?
+
+        definition_key = match[1]
+        definitions.fetch(definition_key) do
+          raise ValidationError.new(path, "unknown $ref #{ref}")
+        end
+      end
+
+      def validate_type(type_spec, value, path)
+        types = Array(type_spec).map(&:to_s)
+        return if types.any? { |type| type_match?(type, value) }
+
+        raise ValidationError.new(path, "expected #{types.join(' or ')}, got #{json_type(value)}")
+      end
+
+      def type_match?(type, value)
+        case type
+        when "null"
+          value.nil?
+        when "boolean"
+          value == true || value == false
+        when "string"
+          value.is_a?(String)
+        when "integer"
+          value.is_a?(Integer)
+        when "number"
+          value.is_a?(Numeric)
+        when "object"
+          value.is_a?(Hash)
+        when "array"
+          value.is_a?(Array)
+        else
+          false
+        end
+      end
+
+      def json_type(value)
+        case value
+        when nil
+          "null"
+        when Hash
+          "object"
+        when Array
+          "array"
+        when String
+          "string"
+        when Integer
+          "integer"
+        when Numeric
+          "number"
+        when TrueClass, FalseClass
+          "boolean"
+        else
+          value.class.name
+        end
+      end
+
+      def validate_enum(options, value, path)
+        return if options.include?(value)
+
+        raise ValidationError.new(path, "must be one of #{options.inspect}")
+      end
+
+      def validate_const(expected, value, path)
+        return if value == expected
+
+        raise ValidationError.new(path, "must be #{expected.inspect}")
+      end
+
+      def validate_format(format, value, path)
+        case format
+        when "int32"
+          validate_integer_range(value, path, -(2**31), (2**31) - 1)
+        when "uint32"
+          validate_integer_range(value, path, 0, (2**32) - 1)
+        when "int64"
+          validate_integer_range(value, path, -(2**63), (2**63) - 1)
+        when "uint64"
+          validate_integer_range(value, path, 0, (2**64) - 1)
+        when "uint16"
+          validate_integer_range(value, path, 0, 65_535)
+        when "double"
+          unless value.is_a?(Numeric)
+            raise ValidationError.new(path, "must be a number for format double")
+          end
+        end
+      end
+
+      def validate_integer_range(value, path, min, max)
+        return unless value.is_a?(Integer)
+        return if value >= min && value <= max
+
+        raise ValidationError.new(path, "must be between #{min} and #{max}")
+      end
+
+      def validate_numeric_bounds(schema, value, path)
+        return unless value.is_a?(Numeric)
+
+        if schema.key?("minimum") && value < schema["minimum"]
+          raise ValidationError.new(path, "must be >= #{schema['minimum']}")
+        end
+        if schema.key?("maximum") && value > schema["maximum"]
+          raise ValidationError.new(path, "must be <= #{schema['maximum']}")
+        end
+      end
+
+      def validate_string_bounds(schema, value, path)
+        return unless value.is_a?(String)
+
+        if schema.key?("minLength") && value.length < schema["minLength"]
+          raise ValidationError.new(path, "length must be >= #{schema['minLength']}")
+        end
+        if schema.key?("maxLength") && value.length > schema["maxLength"]
+          raise ValidationError.new(path, "length must be <= #{schema['maxLength']}")
+        end
+      end
+
+      def validate_array_bounds(schema, value, path)
+        return unless value.is_a?(Array)
+
+        if schema.key?("minItems") && value.length < schema["minItems"]
+          raise ValidationError.new(path, "item count must be >= #{schema['minItems']}")
+        end
+        if schema.key?("maxItems") && value.length > schema["maxItems"]
+          raise ValidationError.new(path, "item count must be <= #{schema['maxItems']}")
+        end
+      end
+
+      def validate_object(schema, value, definitions, path)
+        return unless value.is_a?(Hash)
+
+        required = Array(schema["required"])
+        properties = schema["properties"].is_a?(Hash) ? schema["properties"] : {}
+        additional = schema.key?("additionalProperties") ? schema["additionalProperties"] : true
+        object = value.each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+
+        required.each do |key|
+          next if object.key?(key)
+
+          raise ValidationError.new(path_for_key(path, key), "is required")
+        end
+
+        object.each do |key, nested_value|
+          nested_path = path_for_key(path, key)
+          if properties.key?(key)
+            validate_schema(properties[key], nested_value, definitions, nested_path)
+            next
+          end
+
+          if additional == false
+            raise ValidationError.new(nested_path, "additional property is not allowed")
+          end
+
+          validate_schema(additional, nested_value, definitions, nested_path) if additional.is_a?(Hash)
+        end
+      end
+
+      def validate_items(items_schema, value, definitions, path)
+        return unless value.is_a?(Array)
+
+        case items_schema
+        when Array
+          items_schema.each_with_index do |item_schema, index|
+            break if index >= value.length
+
+            validate_schema(item_schema, value[index], definitions, "#{path}[#{index}]")
+          end
+        else
+          value.each_with_index do |item, index|
+            validate_schema(items_schema, item, definitions, "#{path}[#{index}]")
+          end
+        end
+      end
+
+      def validate_all_of(schemas, value, definitions, path)
+        schemas.each do |sub_schema|
+          validate_schema(sub_schema, value, definitions, path)
+        end
+      end
+
+      def validate_any_of(schemas, value, definitions, path)
+        errors = []
+        schemas.each do |sub_schema|
+          validate_schema(sub_schema, value, definitions, path)
+          return
+        rescue ValidationError => e
+          errors << e
+        end
+
+        closest = closest_error(errors, path)
+        raise ValidationError.new(
+          path,
+          "must match anyOf (closest mismatch at #{closest.path}: #{closest.message})"
+        )
+      end
+
+      def validate_one_of(schemas, value, definitions, path)
+        matches = 0
+        errors = []
+
+        schemas.each do |sub_schema|
+          validate_schema(sub_schema, value, definitions, path)
+          matches += 1
+        rescue ValidationError => e
+          errors << e
+        end
+
+        return if matches == 1
+
+        if matches.zero?
+          closest = closest_error(errors, path)
+          raise ValidationError.new(
+            path,
+            "must match exactly one schema in oneOf (closest mismatch at #{closest.path}: #{closest.message})"
+          )
+        end
+
+        raise ValidationError.new(path, "must match exactly one schema in oneOf (matched #{matches})")
+      end
+
+      def closest_error(errors, path)
+        errors.max_by { |error| error.path.length } || ValidationError.new(path, "is invalid")
+      end
+
+      def path_for_key(path, key)
+        key = key.to_s
+        return "#{path}.#{key}" if key.match?(/\A[A-Za-z_][A-Za-z0-9_]*\z/)
+
+        "#{path}[#{key.inspect}]"
+      end
+
+      def protocol_version_legacy_string?(schema, value, definitions)
+        return false unless value.is_a?(String)
+
+        protocol_version_schema = definitions["ProtocolVersion"]
+        return false if protocol_version_schema.nil?
+
+        schema.equal?(protocol_version_schema) || schema == protocol_version_schema
+      end
+    end
+  end
+end

data/lib/agent_client_protocol/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  VERSION = "0.1.0"
+end

data/lib/agent_client_protocol.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "agent_client_protocol/version"
+require_relative "agent_client_protocol/protocol_version"
+require_relative "agent_client_protocol/error"
+require_relative "agent_client_protocol/schema_registry"
+require_relative "agent_client_protocol/methods"
+require_relative "agent_client_protocol/types"
+require_relative "agent_client_protocol/type_registry"
+require_relative "agent_client_protocol/validator"
+require_relative "agent_client_protocol/rpc"
+require_relative "agent_client_protocol/decoder"
+require_relative "agent_client_protocol/codec"
+require_relative "agent_client_protocol/constants"
+
+module AgentClientProtocol
+  AGENT_METHOD_NAMES = Methods.agent.freeze
+  CLIENT_METHOD_NAMES = Methods.client.freeze
+
+  UNSTABLE_AGENT_METHOD_NAMES = Methods.agent(unstable: true).freeze
+  UNSTABLE_CLIENT_METHOD_NAMES = Methods.client(unstable: true).freeze
+  PROTOCOL_METHOD_NAMES = Methods.protocol(unstable: true).freeze
+
+  module_function
+
+  def type_for(definition_name, unstable: false)
+    TypeRegistry.fetch(definition_name, unstable: unstable)
+  end
+
+  def build_typed(definition_name, payload, unstable: false)
+    TypeRegistry.build(definition_name, payload, unstable: unstable)
+  end
+
+  def validate(definition_name, payload, unstable: false)
+    Validator.validate(definition_name, payload, unstable: unstable)
+  end
+
+  def codec(side:, unstable: false, validate_schema: true)
+    Codec.new(side: side, unstable: unstable, validate_schema: validate_schema)
+  end
+end

data/schema/meta.json

@@ -0,0 +1,24 @@
+{
+  "agentMethods": {
+    "authenticate": "authenticate",
+    "initialize": "initialize",
+    "session_cancel": "session/cancel",
+    "session_load": "session/load",
+    "session_new": "session/new",
+    "session_prompt": "session/prompt",
+    "session_set_config_option": "session/set_config_option",
+    "session_set_mode": "session/set_mode"
+  },
+  "clientMethods": {
+    "fs_read_text_file": "fs/read_text_file",
+    "fs_write_text_file": "fs/write_text_file",
+    "session_request_permission": "session/request_permission",
+    "session_update": "session/update",
+    "terminal_create": "terminal/create",
+    "terminal_kill": "terminal/kill",
+    "terminal_output": "terminal/output",
+    "terminal_release": "terminal/release",
+    "terminal_wait_for_exit": "terminal/wait_for_exit"
+  },
+  "version": 1
+}