agent-client-protocol 0.1.0

data/lib/agent_client_protocol/error.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  module ErrorCode
+    PARSE_ERROR = -32_700
+    INVALID_REQUEST = -32_600
+    METHOD_NOT_FOUND = -32_601
+    INVALID_PARAMS = -32_602
+    INTERNAL_ERROR = -32_603
+    REQUEST_CANCELLED = -32_800
+    AUTH_REQUIRED = -32_000
+    RESOURCE_NOT_FOUND = -32_002
+
+    DEFAULT_MESSAGES = {
+      PARSE_ERROR => "Parse error",
+      INVALID_REQUEST => "Invalid request",
+      METHOD_NOT_FOUND => "Method not found",
+      INVALID_PARAMS => "Invalid params",
+      INTERNAL_ERROR => "Internal error",
+      REQUEST_CANCELLED => "Request cancelled",
+      AUTH_REQUIRED => "Authentication required",
+      RESOURCE_NOT_FOUND => "Resource not found"
+    }.freeze
+
+    module_function
+
+    def default_message(code)
+      DEFAULT_MESSAGES.fetch(code, "Unknown error")
+    end
+  end
+
+  class Error < StandardError
+    attr_reader :code, :data
+
+    def initialize(code:, message: nil, data: nil)
+      @code = Integer(code)
+      @data = data
+      super(message || ErrorCode.default_message(@code))
+    end
+
+    def to_h
+      error = {
+        "code" => code,
+        "message" => message
+      }
+      error["data"] = data unless data.nil?
+      error
+    end
+
+    class << self
+      def from_h(hash)
+        normalized = stringify_keys(hash)
+        new(
+          code: normalized.fetch("code"),
+          message: normalized["message"],
+          data: normalized["data"]
+        )
+      end
+
+      def parse_error(data = nil)
+        new(code: ErrorCode::PARSE_ERROR, data: data)
+      end
+
+      def invalid_request(data = nil)
+        new(code: ErrorCode::INVALID_REQUEST, data: data)
+      end
+
+      def method_not_found(data = nil)
+        new(code: ErrorCode::METHOD_NOT_FOUND, data: data)
+      end
+
+      def invalid_params(data = nil)
+        new(code: ErrorCode::INVALID_PARAMS, data: data)
+      end
+
+      def internal_error(data = nil)
+        new(code: ErrorCode::INTERNAL_ERROR, data: data)
+      end
+
+      def request_cancelled(data = nil)
+        new(code: ErrorCode::REQUEST_CANCELLED, data: data)
+      end
+
+      def auth_required(data = nil)
+        new(code: ErrorCode::AUTH_REQUIRED, data: data)
+      end
+
+      def resource_not_found(uri = nil)
+        payload = uri.nil? ? nil : { "uri" => uri }
+        new(code: ErrorCode::RESOURCE_NOT_FOUND, data: payload)
+      end
+
+      private
+
+      def stringify_keys(value)
+        return value unless value.is_a?(Hash)
+
+        value.each_with_object({}) do |(k, v), acc|
+          acc[k.to_s] = v
+        end
+      end
+    end
+  end
+end

data/lib/agent_client_protocol/methods.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  module Methods
+    module_function
+
+    def agent(unstable: false)
+      SchemaRegistry.agent_methods(unstable: unstable)
+    end
+
+    def client(unstable: false)
+      SchemaRegistry.client_methods(unstable: unstable)
+    end
+
+    def protocol(unstable: false)
+      SchemaRegistry.protocol_methods(unstable: unstable)
+    end
+  end
+end

data/lib/agent_client_protocol/protocol_version.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  class ProtocolVersion
+    include Comparable
+
+    V0 = 0
+    V1 = 1
+    LATEST = V1
+    MAX_VALUE = 65_535
+
+    attr_reader :value
+
+    def initialize(value)
+      unless value.is_a?(Integer) && value >= 0 && value <= MAX_VALUE
+        raise ArgumentError, "protocol version must be an Integer between 0 and #{MAX_VALUE}"
+      end
+
+      @value = value
+    end
+
+    def self.parse(raw)
+      case raw
+      when Integer
+        new(raw)
+      when String
+        # ACP legacy behavior: old string versions map to protocol version 0.
+        new(V0)
+      else
+        raise ArgumentError, "protocol version must be an Integer or String"
+      end
+    end
+
+    def <=>(other)
+      other_value = other.is_a?(ProtocolVersion) ? other.value : other
+      value <=> other_value
+    end
+
+    def ==(other)
+      other_value = other.is_a?(ProtocolVersion) ? other.value : other
+      value == other_value
+    end
+
+    def to_i
+      value
+    end
+
+    def to_h
+      value
+    end
+
+    def to_s
+      value.to_s
+    end
+  end
+end

data/lib/agent_client_protocol/rpc.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AgentClientProtocol
+  module RPC
+    JSONRPC_VERSION = "2.0"
+
+    module_function
+
+    def parse(message)
+      normalized = normalize_input(message)
+
+      if normalized.key?("jsonrpc") && normalized["jsonrpc"] != JSONRPC_VERSION
+        raise Error.invalid_request("unsupported jsonrpc version: #{normalized['jsonrpc']}")
+      end
+
+      if normalized.key?("method")
+        return Request.new(
+          id: normalized["id"],
+          method: normalized["method"],
+          params: normalized["params"]
+        ) if normalized.key?("id")
+
+        return Notification.new(method: normalized["method"], params: normalized["params"])
+      end
+
+      if normalized.key?("result") || normalized.key?("error")
+        response_kwargs = { id: normalized["id"] }
+        response_kwargs[:result] = normalized["result"] if normalized.key?("result")
+        response_kwargs[:error] = normalized["error"] if normalized.key?("error")
+        return Response.new(**response_kwargs)
+      end
+
+      raise Error.invalid_request("message is neither request, response, nor notification")
+    end
+
+    def parse_json(json)
+      parse(JSON.parse(json))
+    rescue JSON::ParserError => e
+      raise Error.parse_error(e.message)
+    end
+
+    def normalize_input(message)
+      case message
+      when String
+        JSON.parse(message)
+      when Hash
+        deep_stringify_keys(message)
+      else
+        raise ArgumentError, "message must be a Hash or JSON String"
+      end
+    end
+
+    def deep_stringify_keys(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(k, v), result|
+          result[k.to_s] = deep_stringify_keys(v)
+        end
+      when Array
+        value.map { |item| deep_stringify_keys(item) }
+      else
+        value
+      end
+    end
+
+    class Request
+      attr_reader :id, :method, :params
+
+      def initialize(id:, method:, params: nil)
+        @id = RequestId.coerce(id)
+        @method = String(method)
+        @params = params
+      end
+
+      def to_h(include_jsonrpc: true)
+        payload = {
+          "id" => id,
+          "method" => method
+        }
+        payload["params"] = params unless params.nil?
+        include_jsonrpc ? { "jsonrpc" => JSONRPC_VERSION }.merge(payload) : payload
+      end
+    end
+
+    class Notification
+      attr_reader :method, :params
+
+      def initialize(method:, params: nil)
+        @method = String(method)
+        @params = params
+      end
+
+      def to_h(include_jsonrpc: true)
+        payload = { "method" => method }
+        payload["params"] = params unless params.nil?
+        include_jsonrpc ? { "jsonrpc" => JSONRPC_VERSION }.merge(payload) : payload
+      end
+    end
+
+    class Response
+      attr_reader :id, :result, :error
+
+      def initialize(id:, result: :__undefined__, error: :__undefined__)
+        @id = RequestId.coerce(id)
+        has_result = result != :__undefined__
+        has_error = error != :__undefined__
+
+        if has_result == has_error
+          raise ArgumentError, "response must have exactly one of result or error"
+        end
+
+        @result = has_result ? result : nil
+        @error = normalize_error(error) if has_error
+      end
+
+      def success?
+        error.nil?
+      end
+
+      def failure?
+        !success?
+      end
+
+      def to_h(include_jsonrpc: true)
+        payload = { "id" => id }
+        if success?
+          payload["result"] = result
+        else
+          payload["error"] = error.is_a?(Error) ? error.to_h : error
+        end
+
+        include_jsonrpc ? { "jsonrpc" => JSONRPC_VERSION }.merge(payload) : payload
+      end
+
+      private
+
+      def normalize_error(error)
+        return error if error.is_a?(Error)
+        return Error.from_h(error) if error.is_a?(Hash)
+
+        raise ArgumentError, "error must be an AgentClientProtocol::Error or a Hash"
+      end
+    end
+
+    module RequestId
+      module_function
+
+      def coerce(value)
+        case value
+        when nil, String, Integer
+          value
+        else
+          raise ArgumentError, "request id must be nil, String, or Integer"
+        end
+      end
+    end
+  end
+end

data/lib/agent_client_protocol/schema_registry.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "json"
+
+module AgentClientProtocol
+  class SchemaRegistry
+    ROOT = File.expand_path("../..", __dir__)
+    STABLE_SCHEMA_PATH = File.join(ROOT, "schema", "schema.json")
+    UNSTABLE_SCHEMA_PATH = File.join(ROOT, "schema", "schema.unstable.json")
+    STABLE_META_PATH = File.join(ROOT, "schema", "meta.json")
+    UNSTABLE_META_PATH = File.join(ROOT, "schema", "meta.unstable.json")
+
+    class << self
+      def stable_schema
+        @stable_schema ||= load_json(STABLE_SCHEMA_PATH)
+      end
+
+      def unstable_schema
+        @unstable_schema ||= load_json(UNSTABLE_SCHEMA_PATH)
+      end
+
+      def stable_meta
+        @stable_meta ||= symbolize_keys(load_json(STABLE_META_PATH))
+      end
+
+      def unstable_meta
+        @unstable_meta ||= symbolize_keys(load_json(UNSTABLE_META_PATH))
+      end
+
+      def defs(unstable: false)
+        schema = unstable ? unstable_schema : stable_schema
+        schema.fetch("$defs")
+      end
+
+      def method_catalog(unstable: false)
+        key = unstable ? :unstable : :stable
+        @method_catalog ||= {}
+        @method_catalog[key] ||= build_method_catalog(defs(unstable: unstable))
+      end
+
+      def agent_methods(unstable: false)
+        meta = unstable ? unstable_meta : stable_meta
+        (meta[:agentMethods] || {}).dup
+      end
+
+      def client_methods(unstable: false)
+        meta = unstable ? unstable_meta : stable_meta
+        (meta[:clientMethods] || {}).dup
+      end
+
+      def protocol_methods(unstable: false)
+        meta = unstable ? unstable_meta : stable_meta
+        (meta[:protocolMethods] || {}).dup
+      end
+
+      def schema_for(definition_name, unstable: false)
+        defs(unstable: unstable).fetch(definition_name)
+      end
+
+      private
+
+      def load_json(path)
+        JSON.parse(File.read(path))
+      end
+
+      def build_method_catalog(definitions)
+        catalog = Hash.new { |h, side| h[side] = {} }
+
+        definitions.each do |definition_name, schema|
+          side = schema["x-side"]
+          method = schema["x-method"]
+          next if side.nil? || method.nil?
+
+          kind = infer_kind(definition_name)
+          next if kind.nil?
+
+          side_key = side.to_sym
+          method_entry = catalog[side_key][method] ||= {}
+          method_entry[kind] = definition_name
+        end
+
+        catalog.each_value do |methods|
+          methods.each_value(&:freeze)
+          methods.freeze
+        end
+
+        catalog.freeze
+      end
+
+      def infer_kind(definition_name)
+        return :request if definition_name.end_with?("Request")
+        return :response if definition_name.end_with?("Response")
+        return :notification if definition_name.end_with?("Notification")
+
+        nil
+      end
+
+      def symbolize_keys(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(k, v), result|
+            result[k.to_sym] = symbolize_keys(v)
+          end
+        when Array
+          value.map { |item| symbolize_keys(item) }
+        else
+          value
+        end
+      end
+    end
+  end
+end

data/lib/agent_client_protocol/type_registry.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module AgentClientProtocol
+  module Types
+    module Unstable
+    end
+  end
+
+  class TypeRegistry
+    @mutex = Mutex.new
+    @loaded = {}
+
+    class << self
+      def fetch(definition_name, unstable: false)
+        ensure_loaded!(unstable: unstable)
+        namespace = unstable ? Types::Unstable : Types
+        return nil unless namespace.const_defined?(definition_name, false)
+
+        namespace.const_get(definition_name, false)
+      end
+
+      def all(unstable: false)
+        ensure_loaded!(unstable: unstable)
+        namespace = unstable ? Types::Unstable : Types
+
+        namespace.constants(false).sort.each_with_object({}) do |const_name, acc|
+          klass = namespace.const_get(const_name, false)
+          next unless klass.is_a?(Class)
+          next unless klass.respond_to?(:definition_name)
+          next if klass.definition_name.nil?
+
+          acc[const_name.to_s] = klass
+        end
+      end
+
+      def build(definition_name, payload, unstable: false)
+        klass = fetch(definition_name, unstable: unstable)
+        return payload if klass.nil?
+
+        klass.coerce(payload)
+      end
+
+      private
+
+      def ensure_loaded!(unstable: false)
+        key = unstable ? :unstable : :stable
+        return if @loaded[key]
+
+        @mutex.synchronize do
+          return if @loaded[key]
+
+          namespace = unstable ? Types::Unstable : Types
+          definitions = SchemaRegistry.defs(unstable: unstable)
+          build_types!(namespace, definitions, unstable: unstable)
+
+          @loaded[key] = true
+        end
+      end
+
+      def build_types!(namespace, definitions, unstable:)
+        definitions.each do |definition_name, schema|
+          next if namespace.const_defined?(definition_name, false)
+
+          parent = object_schema?(schema) ? Types::Base : Types::Scalar
+          klass = Class.new(parent)
+          if parent == Types::Scalar
+            klass.configure(
+              definition_name: definition_name,
+              schema: schema,
+              unstable: unstable,
+              coercer: scalar_coercer_for(definition_name)
+            )
+          else
+            klass.configure(
+              definition_name: definition_name,
+              schema: schema,
+              unstable: unstable
+            )
+          end
+
+          namespace.const_set(definition_name, klass)
+        end
+      end
+
+      def object_schema?(schema)
+        schema["type"] == "object" || schema.key?("properties")
+      end
+
+      def scalar_coercer_for(definition_name)
+        case definition_name
+        when "ProtocolVersion"
+          lambda { |value| ::AgentClientProtocol::ProtocolVersion.parse(value).to_i }
+        else
+          nil
+        end
+      end
+    end
+  end
+end