hitch-rails 0.2.0

data/app/models/hitch/mcp/internal/registry_runtime.rb

@@ -0,0 +1,312 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    module Internal
+      # Validates Registry declarations into the persistent snapshot at
+      # prepare time and resolves listings and calls against it per request.
+      # The snapshot retains only class names and frozen data.
+      class RegistryRuntime
+        CONSTANT_NAME_PATTERN = /\A[A-Z][A-Za-z0-9_]*(?:::[A-Z][A-Za-z0-9_]*)*\z/
+        OAUTH_SCOPE_PATTERN = /\A[\x21\x23-\x5B\x5D-\x7E]+\z/
+        MAX_SCOPE_BYTES = 64
+        ANNOTATION_KEYS = {
+          "title" => :title,
+          "readOnlyHint" => :read_only_hint,
+          "read_only_hint" => :read_only_hint,
+          "destructiveHint" => :destructive_hint,
+          "destructive_hint" => :destructive_hint,
+          "idempotentHint" => :idempotent_hint,
+          "idempotent_hint" => :idempotent_hint,
+          "openWorldHint" => :open_world_hint,
+          "open_world_hint" => :open_world_hint
+        }.freeze
+
+        Entry = Data.define(
+          :class_name,
+          :name,
+          :description,
+          :input_schema,
+          :output_schema,
+          :annotations,
+          :scopes,
+          # The SDK tool wrapper (anonymous ::MCP::Tool subclass) compiled once
+          # here at prepare time instead of per tool per request. It holds only
+          # frozen entry data — never the reloadable host tool class.
+          :sdk_tool
+        )
+        Snapshot = Data.define(:registry_name, :entries)
+        CallResolution = Data.define(:status, :tool, :required_scopes)
+        RuntimeTool = Data.define(:entry, :tool_class) do
+          def name = entry.name
+          def description = entry.description
+          def input_schema = entry.input_schema
+          def output_schema = entry.output_schema
+          def annotations = entry.annotations
+          def sdk_tool = entry.sdk_tool
+
+          def call(server_context:, **arguments)
+            tool_class.call(server_context:, **arguments)
+          end
+        end
+
+        class << self
+          def build_snapshot(registry_name:, supported_scopes:)
+            registry_class = resolve_named_constant(registry_name, "registry")
+            unless registry_class.is_a?(Class) && registry_class < Registry
+              raise ArgumentError, "mcp.registry must resolve to a Hitch::MCP::Registry subclass"
+            end
+
+            supported = validate_supported_scopes(supported_scopes)
+            entries = registry_class.declarations.each_with_index.map do |declaration, index|
+              build_entry(declaration, index:, supported_scopes: supported)
+            end
+            duplicate_names = entries.map(&:name).tally.select { |_name, count| count > 1 }.keys
+            unless duplicate_names.empty?
+              raise ArgumentError, "mcp.registry contains duplicate tool names: #{duplicate_names.sort.join(', ')}"
+            end
+
+            Snapshot.new(
+              registry_name: registry_name.dup.freeze,
+              entries: entries.sort_by(&:name).freeze
+            )
+          # Names what failed to resolve. A host reading this at boot has a
+          # typo in one line of one file, and the line is the message.
+          rescue NameError => error
+            raise ArgumentError, "mcp.registry could not be built: #{error.message}"
+          end
+
+          def runtime_listing(snapshot:, context:)
+            validate_snapshot!(snapshot)
+
+            snapshot.entries.filter_map do |entry|
+              runtime_tool = available_runtime_tool(entry, context)
+              runtime_tool if runtime_tool && scopes_granted?(entry.scopes, context)
+            end.freeze
+          end
+
+          def runtime_call(snapshot:, name:, context:)
+            validate_snapshot!(snapshot)
+            entry = snapshot.entries.find { |candidate| candidate.name == name }
+            return hidden_call_resolution unless entry
+
+            runtime_tool = available_runtime_tool(entry, context)
+            return hidden_call_resolution unless runtime_tool
+
+            unless scopes_granted?(entry.scopes, context)
+              return CallResolution.new(
+                status: :insufficient_scope,
+                tool: nil,
+                required_scopes: entry.scopes
+              )
+            end
+
+            CallResolution.new(
+              status: :available,
+              tool: runtime_tool,
+              required_scopes: [].freeze
+            )
+          end
+
+          private
+
+          def available_runtime_tool(entry, context)
+            tool_class = resolve_named_constant(entry.class_name, "mcp.registry tool")
+            unless tool_class.is_a?(Class) && tool_class < Tool &&
+                tool_class.name == entry.class_name && tool_class.tool_name == entry.name &&
+                tool_class.method(:call).owner == Tool.singleton_class
+              raise ArgumentError,
+                "MCP registry is unavailable: #{entry.class_name} no longer matches its registered snapshot"
+            end
+
+            available = tool_class.available_to?(context)
+            unless available == true || available == false
+              raise ArgumentError, "#{entry.class_name}.available_to? must return true or false"
+            end
+            return unless available
+
+            RuntimeTool.new(entry:, tool_class:)
+          rescue NameError
+            raise ArgumentError, "MCP registry is unavailable: #{entry.class_name} could not be resolved"
+          end
+
+          def scopes_granted?(required_scopes, context)
+            granted_scopes = context.granted_scopes
+            unless granted_scopes.instance_of?(Array) && granted_scopes.all?(String)
+              raise ArgumentError, "MCP context scopes are unavailable"
+            end
+
+            required_scopes.all? { |scope| granted_scopes.include?(scope) }
+          end
+
+          def hidden_call_resolution
+            CallResolution.new(status: :hidden, tool: nil, required_scopes: [].freeze)
+          end
+
+          def validate_snapshot!(snapshot)
+            unless snapshot.instance_of?(Snapshot)
+              raise ArgumentError, "MCP registry is unavailable: no snapshot has been prepared"
+            end
+          end
+
+          def build_entry(declaration, index:, supported_scopes:)
+            class_name = declaration.class_name
+            unless class_name.is_a?(String) && CONSTANT_NAME_PATTERN.match?(class_name)
+              raise ArgumentError,
+                "mcp.registry entry #{index + 1} got #{declaration.source}; " \
+                "register a named Hitch::MCP::Tool subclass, as in `register EchoTool`"
+            end
+
+            # Named from here on. Counting registry entries at someone whose
+            # registry is a list of class names makes them count too.
+            label = "mcp.registry tool #{class_name}"
+
+            tool_class = resolve_named_constant(class_name, "#{label} tool")
+            unless tool_class.is_a?(Class) && tool_class < Tool
+              raise ArgumentError, "#{label} must register a Hitch::MCP::Tool subclass"
+            end
+            unless tool_class.method(:call).owner == Tool.singleton_class
+              raise ArgumentError, "#{label} must not override framework-owned .call"
+            end
+
+            name = validate_tool_name(tool_class.tool_name, label)
+            description = validate_description(tool_class.description, label)
+            input_schema = SchemaContract.new(
+              tool_class.input_schema,
+              label: "#{label} input_schema"
+            ).call
+            if declares_server_context?(input_schema)
+              raise ArgumentError,
+                "#{label} input_schema must not name server_context at the top level"
+            end
+            output_schema = if tool_class.output_schema.nil?
+              nil
+            else
+              SchemaContract.new(
+                tool_class.output_schema,
+                label: "#{label} output_schema"
+              ).call
+            end
+            annotations = validate_annotations(tool_class.annotations, label)
+            scopes = validate_scopes(declaration.scopes, label, supported_scopes)
+
+            Entry.new(
+              class_name: class_name.dup.freeze,
+              name:,
+              description:,
+              input_schema:,
+              output_schema:,
+              annotations:,
+              scopes:,
+              sdk_tool: SDKAdapter.build_sdk_tool(
+                name:, description:, input_schema:, output_schema:, annotations:
+              )
+            )
+          end
+
+          # server_context is Hitch's own channel to the tool, and the wire
+          # refuses it as an argument, so a schema naming it can never be
+          # satisfied: every call would fail with "Missing required
+          # arguments". Caught once at boot instead of on every request.
+          #
+          # Top level only. A nested server_context is ordinary tool data, and
+          # one reached through $ref or allOf is not caught here — chasing
+          # those was 28 lines of recursion for a key nobody names by
+          # accident.
+          def declares_server_context?(schema)
+            properties = schema["properties"]
+            (properties.is_a?(Hash) && properties.key?("server_context")) ||
+              Array(schema["required"]).include?("server_context")
+          end
+
+          def validate_tool_name(value, label)
+            unless Protocol.tool_name?(value)
+              raise ArgumentError,
+                "#{label} tool_name must be 1-#{Protocol::MAX_TOOL_NAME_LENGTH} ASCII letters, " \
+                  "digits, underscore, dot, or dash"
+            end
+
+            value.dup.freeze
+          end
+
+          def validate_description(value, label)
+            unless value.is_a?(String) && value.match?(/\S/)
+              raise ArgumentError, "#{label} description must be a nonblank String"
+            end
+
+            value.dup.freeze
+          end
+
+          def validate_annotations(value, label)
+            return if value.nil?
+            raise ArgumentError, "#{label} annotations must be a Hash" unless value.is_a?(Hash)
+
+            value.each_with_object({}) do |(key, annotation_value), normalized|
+              canonical = ANNOTATION_KEYS[key.to_s]
+              raise ArgumentError, "#{label} contains an unsupported annotation" unless canonical
+              raise ArgumentError, "#{label} contains a duplicate annotation" if normalized.key?(canonical)
+
+              normalized[canonical] = if canonical == :title
+                unless annotation_value.is_a?(String) && annotation_value.match?(/\S/)
+                  raise ArgumentError, "#{label} annotation title must be a nonblank String"
+                end
+                annotation_value.dup.freeze
+              else
+                unless annotation_value == true || annotation_value == false
+                  raise ArgumentError, "#{label} tool hint annotations must be Boolean"
+                end
+                annotation_value
+              end
+            end.freeze
+          end
+
+          def validate_scopes(scopes, label, supported_scopes)
+            unless scopes.is_a?(Array) && !scopes.empty?
+              raise ArgumentError, "#{label} scopes must be a nonempty Array"
+            end
+            unless scopes.all? do |scope|
+              scope.is_a?(String) && scope.bytesize <= MAX_SCOPE_BYTES && OAUTH_SCOPE_PATTERN.match?(scope)
+            end
+              raise ArgumentError, "#{label} scopes must contain valid OAuth scope tokens"
+            end
+            unless scopes.uniq.length == scopes.length
+              raise ArgumentError, "#{label} scopes must not contain duplicates"
+            end
+
+            unsupported = scopes - supported_scopes
+            unless unsupported.empty?
+              raise ArgumentError, "#{label} scopes are not present in Hitch.configuration.supported_scopes"
+            end
+
+            scopes.map { |scope| scope.dup.freeze }.freeze
+          end
+
+          def validate_supported_scopes(scopes)
+            unless scopes.is_a?(Array) && scopes.all?(String)
+              raise ArgumentError, "supported_scopes must be an Array of Strings"
+            end
+
+            scopes
+          end
+
+          def resolve_named_constant(name, label)
+            unless name.is_a?(String) && CONSTANT_NAME_PATTERN.match?(name)
+              raise ArgumentError, "#{label} must be a named constant"
+            end
+
+            constant = name.split("::").reduce(Object) do |namespace, part|
+              raise NameError, "#{label} #{name} is not a resolvable constant" unless namespace.is_a?(Module)
+
+              namespace.const_get(part, false)
+            end
+            unless constant.respond_to?(:name) && constant.name == name
+              raise ArgumentError, "#{label} must resolve to its exact named constant"
+            end
+
+            constant
+          end
+        end
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/internal/result_normalizer.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+require "json"
+require "json_schemer"
+
+module Hitch
+  module MCP
+    module Internal
+      # Converts the closed host Result into the one exact SDK response that was
+      # independently schema-validated and measured before SDK validation.
+      class ResultNormalizer
+        JSON_SCHEMA_2020_12 = "https://json-schema.org/draft/2020-12/schema"
+        ROOT_SCHEMA_KEYWORDS = %w[type $ref oneOf anyOf allOf not if const enum].freeze
+
+        class Failure < StandardError
+          attr_reader :category
+
+          def initialize(category)
+            @category = category
+            super("Hitch MCP result normalization failed")
+          end
+        end
+
+        # Duck-typed stand-in for ::MCP::Tool::Response — both supported SDK
+        # lines read only #to_h and #content_provided?. explicit_error_text is
+        # the host-authored Result.error string, carried out of band so the
+        # response normalizer can tell it apart from SDK-generated errors.
+        class SDKResponse
+          attr_reader :explicit_error_text
+
+          def initialize(result, content_provided:, explicit_error_text: nil)
+            @hitch_result = result
+            @hitch_content_provided = content_provided
+            @explicit_error_text = explicit_error_text
+          end
+
+          def to_h
+            JsonValues.copy(@hitch_result)
+          end
+
+          def content_provided?
+            @hitch_content_provided
+          end
+        end
+
+        class << self
+          def call(result:, output_schema:, max_bytes:)
+            new(result, output_schema, max_bytes).call
+          end
+
+          def failure_category(error)
+            error.category if error.instance_of?(Failure)
+          end
+
+          def explicit_error_text(response)
+            response.explicit_error_text if response.instance_of?(SDKResponse)
+          end
+        end
+
+        def initialize(result, output_schema, max_bytes)
+          @result = result
+          @output_schema = output_schema
+          @max_bytes = max_bytes
+        end
+
+        def call
+          invalid!(:invalid_result_type) unless result.instance_of?(Result)
+          invalid!(:invalid_result_limit) unless max_bytes.instance_of?(Integer) && max_bytes.positive?
+
+          canonical, content_provided, explicit_error_text = canonical_result
+          serialized = generate(canonical)
+          invalid!(:result_too_large) if serialized.bytesize > max_bytes
+
+          SDKResponse.new(canonical, content_provided:, explicit_error_text:)
+        rescue SystemStackError
+          invalid!(:serialization_failure)
+        end
+
+        private
+
+        attr_reader :result, :output_schema, :max_bytes
+
+        def canonical_result
+          case result.kind
+          when :text then text_result
+          when :structured then structured_result
+          when :error then error_result
+          else invalid!(:invalid_result_type)
+          end
+        end
+
+        def text_result
+          validate_output_schema!(nil) if output_schema
+          content = text_content(result.value)
+          [ deep_freeze(content: content, isError: false), true, nil ]
+        end
+
+        def structured_result
+          invalid!(:missing_output_schema) unless output_schema
+
+          value = result.value
+          serialized_value = generate(value)
+          validate_output_schema!(value)
+          text = result.text
+          fallback = value.is_a?(Hash) ? nil : serialized_value
+          content = text || fallback
+          canonical = {
+            content: content ? text_content(content) : [],
+            isError: false,
+            structuredContent: value
+          }
+          [ deep_freeze(canonical), !content.nil?, nil ]
+        end
+
+        def error_result
+          text = result.value
+          [ deep_freeze(content: text_content(text), isError: true), true, text ]
+        end
+
+        def validate_output_schema!(value)
+          schema = normalized_output_schema
+          schema = schema.merge("type" => "object") unless ROOT_SCHEMA_KEYWORDS.any? { |key| schema.key?(key) }
+          resolver = ->(uri) { raise JSONSchemer::UnknownRef, uri.to_s }
+          schemer = JSONSchemer.schema(
+            schema,
+            meta_schema: JSON_SCHEMA_2020_12,
+            format: false,
+            ref_resolver: resolver,
+            regexp_resolver: "ruby"
+          )
+          invalid!(:output_schema_mismatch) unless schemer.valid?(value)
+        rescue Failure
+          raise
+        rescue StandardError
+          invalid!(:output_schema_validation_failure)
+        end
+
+        def normalized_output_schema
+          parsed = JSON.parse(generate(output_schema))
+          invalid!(:output_schema_validation_failure) unless parsed.is_a?(Hash)
+
+          parsed
+        end
+
+        def generate(value)
+          JSON.generate(value, max_nesting: false)
+        rescue JSON::GeneratorError, EncodingError
+          invalid!(:serialization_failure)
+        end
+
+        def text_content(text)
+          [ { type: "text", text: text } ]
+        end
+
+        def deep_freeze(value)
+          JsonValues.deep_freeze(value)
+        end
+
+        def invalid!(category)
+          raise Failure, category
+        end
+
+        private_constant :Failure, :SDKResponse
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/internal/sanitized_report.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Hitch
+  module MCP
+    module Internal
+      # Reports a synthetic failure with caller-fixed context through the host
+      # error reporter. The original exception never crosses this boundary, and
+      # every reporting failure is swallowed.
+      class SanitizedReport
+        class ReportedFailure < StandardError; end
+
+        class << self
+          def emit(source:, context:, message:)
+            return unless Rails.respond_to?(:error)
+
+            failure = ReportedFailure.new(message)
+            failure.set_backtrace(caller(1, 8))
+            failure.freeze
+            Rails.error.report(
+              failure,
+              handled: true,
+              severity: :error,
+              context: context,
+              source: source
+            )
+            nil
+          rescue StandardError, SystemStackError
+            nil
+          end
+        end
+
+        private_constant :ReportedFailure
+      end
+    end
+  end
+end

data/app/models/hitch/mcp/internal/schema_contract.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+require "json"
+require "json_schemer"
+require "uri"
+
+module Hitch
+  module MCP
+    module Internal
+      # Admission-time contract for a tool's input or output schema: a bounded,
+      # copied, frozen JSON Schema 2020-12 document with only same-document
+      # references.
+      class SchemaContract
+        MAX_SCHEMA_DEPTH = 64
+        MAX_SCHEMA_OBJECTS = 10_000
+        MAX_SCHEMA_BYTES = 1_048_576
+        JSON_SCHEMA_2020_12 = "https://json-schema.org/draft/2020-12/schema"
+        REFERENCE_KEYS = %w[$ref $dynamicRef].freeze
+
+        def initialize(value, label:)
+          @label = label
+          @schema = copy_schema(value)
+        end
+
+        def call
+          invalid!("must be a JSON object") unless @schema.instance_of?(Hash)
+          invalid!("exceeds #{MAX_SCHEMA_BYTES} serialized bytes") if serialized_bytes > MAX_SCHEMA_BYTES
+
+          validate_dialects_and_references!
+          validate_json_schema!
+
+          @schema
+        end
+
+        private
+
+        attr_reader :label
+
+        def copy_schema(value)
+          JsonValues.copy(
+            value,
+            keys: :stringify_symbols, symbols: :to_s, foreign: :reject,
+            finite: true, duplicates: :reject, freeze: true,
+            max_depth: MAX_SCHEMA_DEPTH, max_objects: MAX_SCHEMA_OBJECTS,
+            on_invalid: method(:copy_invalid!)
+          )
+        end
+
+        def copy_invalid!(reason, detail)
+          invalid!(
+            case reason
+            when :depth then "nesting exceeds #{MAX_SCHEMA_DEPTH}"
+            when :recursive then "contains a recursive Ruby object"
+            when :objects then "exceeds #{MAX_SCHEMA_OBJECTS} schema objects"
+            when :key then "contains a non-string schema key"
+            when :duplicate_key then "contains duplicate key #{detail.inspect}"
+            when :non_finite then "contains a non-finite number"
+            else "contains a non-JSON value"
+            end
+          )
+        end
+
+        def serialized_bytes
+          JSON.generate(@schema, max_nesting: false).bytesize
+        rescue JSON::GeneratorError
+          invalid!("cannot be serialized as JSON")
+        end
+
+        def validate_dialects_and_references!
+          each_schema_value(@schema) do |node|
+            next unless node.is_a?(Hash)
+
+            dialect = node["$schema"]
+            if dialect && dialect != JSON_SCHEMA_2020_12
+              invalid!("must use JSON Schema 2020-12")
+            end
+
+            REFERENCE_KEYS.each do |key|
+              next unless node.key?(key)
+
+              reference = node[key]
+              unless reference.is_a?(String) && reference.start_with?("#")
+                invalid!("supports only same-document #{key} values")
+              end
+              resolve_local_reference(reference)
+            end
+          end
+        end
+
+        def validate_json_schema!
+          resolver = lambda do |uri|
+            raise JSONSchemer::UnknownRef, uri.to_s
+          end
+          schemer = JSONSchemer.schema(
+            @schema,
+            meta_schema: JSON_SCHEMA_2020_12,
+            format: false,
+            ref_resolver: resolver,
+            regexp_resolver: "ruby"
+          )
+          errors = schemer.validate_schema.to_a
+          invalid!("is not a valid JSON Schema 2020-12 document") unless errors.empty?
+        rescue JSONSchemer::InvalidRefResolution, JSONSchemer::InvalidRefPointer,
+          JSONSchemer::UnknownRef, RegexpError, URI::InvalidURIError
+          invalid!("is not a valid JSON Schema 2020-12 document")
+        end
+
+        def resolve_local_reference(reference)
+          fragment = reference.delete_prefix("#")
+          return @schema if fragment.empty?
+
+          decoded = URI::DEFAULT_PARSER.unescape(fragment)
+          invalid!("contains an invalid local reference") unless decoded.valid_encoding?
+
+          if decoded.start_with?("/")
+            decoded.split("/", -1).drop(1).reduce(@schema) do |node, token|
+              key = token.gsub(/~1/, "/").gsub(/~0/, "~")
+              case node
+              when Hash
+                invalid!("contains an unresolved local reference") unless node.key?(key)
+                node.fetch(key)
+              when Array
+                index = Integer(key, exception: false)
+                invalid!("contains an unresolved local reference") unless index && index >= 0 && index < node.length
+                node.fetch(index)
+              else
+                invalid!("contains an unresolved local reference")
+              end
+            end
+          else
+            anchor = find_anchor(@schema, decoded)
+            invalid!("contains an unresolved local reference") unless anchor
+            anchor
+          end
+        rescue ArgumentError
+          invalid!("contains an invalid local reference")
+        end
+
+        def find_anchor(value, name)
+          case value
+          when Hash
+            return value if value["$anchor"] == name || value["$dynamicAnchor"] == name
+
+            value.each_value do |child|
+              found = find_anchor(child, name)
+              return found if found
+            end
+          when Array
+            value.each do |child|
+              found = find_anchor(child, name)
+              return found if found
+            end
+          end
+          nil
+        end
+
+        def each_schema_value(value, &block)
+          yield value
+          case value
+          when Hash
+            value.each_value { |child| each_schema_value(child, &block) }
+          when Array
+            value.each { |child| each_schema_value(child, &block) }
+          end
+        end
+
+        def invalid!(reason)
+          raise ArgumentError, "#{label} #{reason}"
+        end
+      end
+    end
+  end
+end