little_ghost 0.3.0 → 0.5.0

data/lib/little_ghost/mcp/toolset.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module MCP
+    # Connects one MCP server to an Agent as a reusable Tool provider. Each Agent
+    # run gets its own connection. +map_tool+ chooses and configures the generated
+    # Tool classes; +map_result+ converts results that need application-specific
+    # handling.
+    #
+    #   class HelpCenterTools < LittleGhost::MCP::Toolset
+    #     connection url: "https://mcp.example/rpc", timeout: 20
+    #   end
+    #
+    #   class CustomerSupportAgent < LittleGhost::Agent
+    #     tools HelpCenterTools
+    #   end
+    class Toolset
+      extend Support::ClassAttributes
+
+      CONNECTION_OPTIONS = %i[url headers timeout signer allow_insecure_http max_response_bytes].freeze # :nodoc:
+      UNSET = Object.new.freeze # :nodoc:
+
+      class CallbackFailure < Error # :nodoc:
+        attr_reader :original
+
+        def initialize(original)
+          @original = original
+          super(original.message)
+        end
+      end
+
+      class_attribute :connection_value
+      class_attribute :tool_mapping_value
+      class_attribute :result_mapping_value
+      class_attribute :optional_value, default: false
+      class_attribute :error_callback_value
+
+      class << self
+        # Declares a static connection Hash or a block called with the current
+        # Tool::Binding. The Hash requires +url+ and may include
+        # +headers+, +timeout+, +signer+, +allow_insecure_http+, and
+        # +max_response_bytes+.
+        #
+        # :call-seq:
+        #   connection() -> Hash, Proc, nil
+        #   connection(values) -> Hash
+        #   connection { |binding| ... } -> Proc
+        def connection(value = UNSET, &resolver)
+          return connection_value if value.equal?(UNSET) && !resolver
+          raise ArgumentError, "provide a connection or a block, not both" unless value.equal?(UNSET) || !resolver
+
+          configured = resolver || value
+          unless configured.is_a?(Hash) || configured.respond_to?(:call)
+            raise ArgumentError, "connection must be a hash or callable"
+          end
+
+          self.connection_value = configured.is_a?(Hash) ? normalize_connection(configured) : configured
+        end
+
+        # Maps each generated Tool class. The block receives +definition:+ and
+        # +binding:+ keywords. Return the configured Tool class, or nil to omit
+        # it. Changing Tool#tool_name does not change the operation name sent to
+        # the MCP server.
+        #
+        # :call-seq:
+        #   map_tool() -> Proc, nil
+        #   map_tool { |tool_class, definition:, binding:| ... } -> Proc
+        def map_tool(&mapping)
+          return tool_mapping_value unless mapping
+
+          self.tool_mapping_value = mapping
+        end
+
+        # Maps each immutable MCP::Result. The block receives +call:+ and
+        # +binding:+ keywords and returns any Ruby value or Tool::Result.
+        #
+        # :call-seq:
+        #   map_result() -> Proc, nil
+        #   map_result { |result, call:, binding:| ... } -> Proc
+        def map_result(&mapping)
+          return result_mapping_value unless mapping
+
+          self.result_mapping_value = mapping
+        end
+
+        # Makes expected provider and protocol discovery failures produce no
+        # tools. Configuration, cancellation, deadline, and callback failures
+        # still propagate.
+        #
+        # :call-seq:
+        #   optional() -> true or false
+        #   optional(value) -> true or false
+        def optional(value = UNSET)
+          return optional_value if value.equal?(UNSET)
+
+          self.optional_value = !!value
+        end
+
+        # Observes an expected discovery failure caught by <tt>optional true</tt>.
+        # Exceptions raised by this callback propagate.
+        #
+        # :call-seq:
+        #   on_error() -> Proc, nil
+        #   on_error { |error, binding:| ... } -> Proc
+        def on_error(&callback)
+          return error_callback_value unless callback
+
+          self.error_callback_value = callback
+        end
+
+        # Generates Tool classes for an Agent's current binding.
+        def tools(binding)
+          options = resolved_connection(binding)
+          context = binding.run.context if binding.run&.respond_to?(:context)
+          mapper = tool_mapping_value
+          result_mapper = result_mapping_value
+          options = connection_with_wrapped_signer(options)
+          Instrumentation.instrument(:mcp_discovery, toolset: toolset_name) do |telemetry|
+            client = Client.new(
+              transport: HTTPTransport.new(**options),
+              name: toolset_name,
+              tool_mapper: mapper && lambda do |tool_class, definition:, binding:|
+                invoke_application_callback do
+                  mapper.call(tool_class, definition:, binding:)
+                end
+              end,
+              result_mapper: result_mapper && lambda do |result, call:, binding:|
+                result_mapper.call(result, call:, binding:)
+              end
+            )
+            discovered = client.tools(context:, binding:)
+            telemetry[:outcome] = :success
+            telemetry[:tool_count] = discovered.length
+            discovered
+          end
+        rescue CallbackFailure => error
+          raise error.original
+        rescue ProviderError, ProtocolError, ToolError => error
+          raise unless optional_value
+
+          error_callback_value&.call(error, binding:)
+          []
+        end
+
+        private
+
+        def resolved_connection(binding)
+          configured = connection_value
+          raise ConfigurationError, "#{toolset_name} must declare an MCP connection" unless configured
+
+          value = if configured.respond_to?(:call)
+            invoke_application_callback { configured.call(binding) }
+          else
+            configured
+          end
+          normalize_connection(value)
+        end
+
+        def normalize_connection(value)
+          hash = Hash.try_convert(value)
+          raise ConfigurationError, "#{toolset_name} connection must resolve to a hash" unless hash
+
+          normalized = hash.each_with_object({}) do |(name, child), result|
+            key = name.to_sym
+            raise ConfigurationError, "#{toolset_name} connection contains duplicate #{key}" if result.key?(key)
+
+            result[key] = child
+          end
+          unknown = normalized.keys - CONNECTION_OPTIONS
+          unless unknown.empty?
+            raise ConfigurationError, "#{toolset_name} connection contains unknown option #{unknown.first.inspect}"
+          end
+          url = normalized[:url]
+          raise ConfigurationError, "#{toolset_name} connection must include a URL" if url.nil? || url.to_s.empty?
+
+          normalized[:url] = String(url).freeze
+          normalized[:headers] = normalize_headers(normalized.fetch(:headers, {}))
+          normalized.freeze
+        rescue NoMethodError
+          raise ConfigurationError, "#{toolset_name} connection keys must be strings or symbols"
+        end
+
+        def normalize_headers(headers)
+          headers.each_with_object({}) do |(name, value), normalized|
+            normalized[String(name).dup.freeze] = String(value).dup.freeze
+          end.freeze
+        end
+
+        def connection_with_wrapped_signer(options)
+          signer = options[:signer]
+          return options unless signer
+
+          options.merge(
+            signer: ->(request) { invoke_application_callback { signer.call(request) } }
+          ).freeze
+        end
+
+        def invoke_application_callback
+          yield
+        rescue ProviderError, ProtocolError, ToolError => error
+          raise CallbackFailure.new(error)
+        end
+
+        def toolset_name
+          name || "MCP Toolset"
+        end
+      end
+    end
+  end
+end

data/lib/little_ghost/mcp/types.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+module LittleGhost
+  module MCP
+    module ImmutableValue # :nodoc:
+      module_function
+
+      def mapping(value, field:)
+        raise ProtocolError, "MCP #{field} must be an object" unless value.is_a?(Hash)
+
+        freeze_value(DataMap.new(value))
+      rescue ArgumentError => error
+        raise ProtocolError, "MCP #{field} is invalid: #{error.message}"
+      end
+
+      def optional_mapping(value, field:)
+        return if value.nil?
+
+        mapping(value, field:)
+      end
+
+      def array(value, field:)
+        raise ProtocolError, "MCP #{field} must be an array" unless value.is_a?(Array)
+
+        freeze_value(DataMap.new("items" => value).fetch("items"))
+      rescue ArgumentError => error
+        raise ProtocolError, "MCP #{field} is invalid: #{error.message}"
+      end
+
+      def freeze_value(value)
+        pending = [value]
+        until pending.empty?
+          current = pending.pop
+          case current
+          when Hash
+            current.each do |key, child|
+              key.freeze
+              pending << child
+            end
+          when Array
+            current.each { |child| pending << child }
+          end
+          current.freeze
+        end
+        value
+      end
+    end
+
+    Definition = Data.define( # :nodoc:
+      :source_name,
+      :name,
+      :description,
+      :input_schema,
+      :output_schema,
+      :annotations,
+      :title,
+      :metadata,
+      :raw
+    ) do
+      def initialize(source_name:, name:, description:, input_schema:, raw:, output_schema: nil,
+        annotations: {}, title: nil, metadata: {})
+        source_name = String(source_name)
+        name = String(name)
+        raise ProtocolError, "MCP tool definition must include a name" if source_name.empty?
+        raise ConfigurationError, "MCP tool name cannot be empty" if name.empty?
+
+        super(
+          source_name: source_name.freeze,
+          name: name.freeze,
+          description: String(description).freeze,
+          input_schema: ImmutableValue.mapping(input_schema, field: "tool inputSchema"),
+          output_schema: ImmutableValue.optional_mapping(output_schema, field: "tool outputSchema"),
+          annotations: ImmutableValue.mapping(annotations, field: "tool annotations"),
+          title: title.nil? ? nil : String(title).freeze,
+          metadata: ImmutableValue.mapping(metadata, field: "tool _meta"),
+          raw: ImmutableValue.mapping(raw, field: "tool definition")
+        )
+      rescue TypeError
+        raise ProtocolError, "MCP tool definition is invalid"
+      end
+
+      def [](key) = raw[key]
+      def fetch(...) = raw.fetch(...)
+      def dig(...) = raw.dig(...)
+      def key?(key) = raw.key?(key)
+    end
+
+    # Immutable server-advertised Tool metadata. +source_name+ is always the
+    # name sent back to the server; +name+ is the initially generated
+    # model-facing name and may later be customized on the generated Tool class.
+    class Definition < Data # :doc:
+      ##
+      # :attr_reader: source_name
+      # The unmodified server-advertised name used for dispatch.
+
+      ##
+      # :attr_reader: name
+      # The normalized, optionally prefixed initial model-facing name.
+
+      ##
+      # :attr_reader: description
+      # The model-facing description, including LittleGhost's fallback when the
+      # server omitted one.
+
+      ##
+      # :attr_reader: input_schema
+      # The deeply frozen MCP input schema.
+
+      ##
+      # :attr_reader: output_schema
+      # The optional deeply frozen MCP output schema.
+
+      ##
+      # :attr_reader: annotations
+      # Deeply frozen MCP tool annotations.
+
+      ##
+      # :attr_reader: title
+      # The optional human-readable MCP title.
+
+      ##
+      # :attr_reader: metadata
+      # Deeply frozen MCP <tt>_meta</tt> object.
+
+      ##
+      # :attr_reader: raw
+      # A deeply frozen, indifferent-access copy of the complete server
+      # definition object.
+      # Definition also delegates +[]+, +fetch+, +dig+, and +key?+ to this map.
+    end
+
+    Call = Data.define(:definition, :arguments, :context, :binding) do # :nodoc:
+      def initialize(definition:, arguments:, context: nil, binding: Tool::Binding.new)
+        raise ArgumentError, "definition must be a LittleGhost::MCP::Definition" unless definition.is_a?(Definition)
+
+        super(
+          definition:,
+          arguments: ImmutableValue.mapping(arguments, field: "tool call arguments"),
+          context:,
+          binding:
+        )
+      end
+    end
+
+    # Describes one MCP Tool invocation. It combines the server's Definition,
+    # the copied arguments, and the Tool::Binding used to execute the generated
+    # Tool.
+    class Call < Data # :doc:
+      ##
+      # :attr_reader: definition
+      # The Definition whose +source_name+ is sent to the server.
+
+      ##
+      # :attr_reader: arguments
+      # Deeply frozen, indifferent-access arguments.
+
+      ##
+      # :attr_reader: context
+      # The RunContext controlling cancellation, deadlines, and working state.
+
+      ##
+      # :attr_reader: binding
+      # The Tool::Binding for the generated Tool instance.
+    end
+
+    Result = Data.define(:content, :structured_content, :error, :metadata, :raw) do # :nodoc:
+      def initialize(content:, raw:, structured_content: nil, error: false, metadata: {})
+        unless error.nil? || error == true || error == false
+          raise ProtocolError, "MCP tool result isError must be boolean"
+        end
+
+        super(
+          content: ImmutableValue.array(content, field: "tool result content"),
+          structured_content: ImmutableValue.optional_mapping(
+            structured_content,
+            field: "structuredContent"
+          ),
+          error: !!error,
+          metadata: ImmutableValue.mapping(metadata, field: "tool result _meta"),
+          raw: ImmutableValue.mapping(raw, field: "tool result")
+        )
+      end
+
+      def error? = error
+    end
+
+    # Represents one MCP Tool result without discarding server fields. Mapping
+    # callbacks can inspect normalized content, structured content, metadata, or
+    # the complete protocol value.
+    class Result < Data # :doc:
+      ##
+      # :attr_reader: content
+      # Deeply frozen MCP content blocks.
+
+      ##
+      # :attr_reader: structured_content
+      # The optional deeply frozen structured result object.
+
+      ##
+      # :attr_reader: error
+      # Whether the server marked the result with <tt>isError</tt>.
+
+      ##
+      # :attr_reader: metadata
+      # Deeply frozen MCP result <tt>_meta</tt>.
+
+      ##
+      # :attr_reader: raw
+      # A deeply frozen copy of the complete server result object.
+
+      ##
+      # :method: error?
+      # Whether the server marked the result as an error.
+    end
+  end
+end

data/lib/little_ghost/mcp.rb

@@ -2,4 +2,7 @@
 
 # Loads LittleGhost's optional Model Context Protocol client. Requiring
 # +little_ghost+ alone does not load its HTTP integration.
+require_relative "../little_ghost"
+require_relative "mcp/types"
 require_relative "mcp/client"
+require_relative "mcp/toolset"

data/lib/little_ghost/message.rb

@@ -21,8 +21,8 @@ module LittleGhost
     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.
+    # application-defined +metadata+. Metadata becomes a frozen DataMap, so
+    # String and Symbol keys address the same JSON-compatible value.
     def initialize(role:, content:, metadata: {})
       @role = role.to_sym
       raise ArgumentError, "Unsupported message role: #{role.inspect}" unless ROLES.include?(@role)
@@ -35,7 +35,7 @@ module LittleGhost
         [content]
       end
       @content = blocks.map { |block| Content.normalize(block) }.freeze
-      @metadata = metadata.freeze
+      @metadata = DataMap.new(metadata).freeze
       freeze
     end
 
@@ -64,7 +64,7 @@ module LittleGhost
 
     # Produces the JSON-safe message representation.
     def to_h
-      {"role" => role.to_s, "content" => content.map(&:to_h), "metadata" => metadata}
+      {"role" => role.to_s, "content" => content.map(&:to_h), "metadata" => metadata.to_h}
     end
 
     # Encodes #to_h as JSON, forwarding generator +arguments+.

data/lib/little_ghost/model_capabilities.rb

@@ -5,9 +5,10 @@ module LittleGhost
   # 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.
+  # A +nil+ +supported_parameters+ list means the parameter list is not
+  # restricted. Use +ModelCapabilities.unknown+ when metadata is unavailable.
+  # Callers must check +known?+ before treating +supports_parameter?+ as evidence
+  # that a provider supports a feature.
   ModelCapabilities = Data.define( # :nodoc:
     :native_structured_output,
     :tools,
@@ -59,7 +60,8 @@ module LittleGhost
 
   # 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.
+  # A +nil+ supported-parameter list means the list itself is unrestricted.
+  # Check +known?+ before treating that as known provider support.
   class ModelCapabilities < Data # :doc:
     ##
     # :singleton-method: new
@@ -112,8 +114,9 @@ module LittleGhost
     # :call-seq:
     #   supports_parameter?(*names) -> boolean
     #
-    # Checks whether any supplied parameter name is supported. An unrestricted
-    # capability set supports every name.
+    # Checks only the parameter-list restriction. It returns true for every name
+    # when the list is +nil+, including on an unknown capability value. Check
+    # +known?+ when the caller needs evidence of provider support.
 
     ##
     # :singleton-method: permissive

data/lib/little_ghost/model_request.rb

@@ -1,18 +1,6 @@
 # frozen_string_literal: true
 
 module LittleGhost
-  # ModelRequest carries everything a provider needs for one model stream. It
-  # keeps messages, tools, settings, structured-output requirements, and
-  # cooperative execution controls together.
-  #
-  # Messages are coerced into Message objects, and required capabilities are
-  # normalized to unique symbols. The messages, tools, settings, and capability
-  # containers are frozen; output schema and tool choice values are retained as
-  # supplied.
-  #
-  # Only those outer containers are frozen. Do not mutate retained output
-  # schemas, tool choices, or nested settings after construction, and do not
-  # share mutable control values across concurrent requests.
   ModelRequest = Data.define( # :nodoc:
     :messages,
     :tools,

data/lib/little_ghost/model_resolver.rb

@@ -1,9 +1,19 @@
 # frozen_string_literal: true
 
 module LittleGhost
-  # Resolves logical profiles, canonical +provider:model-id+ targets, and inline
-  # model mappings into executable Model objects. Subclasses may override
-  # #resolve, #details, or #refresh! while preserving those public signatures.
+  # Maps an application model role to an executable Model.
+  #
+  #   resolver = LittleGhost::ModelResolver.new(
+  #     profiles: {
+  #       customer_support: {target: "openrouter:openai/gpt-5.6-luna"}
+  #     }
+  #   )
+  #   # With OPENROUTER_API_KEY set:
+  #   model = resolver.resolve(:customer_support)
+  #
+  # A role is an application-facing name such as +:customer_support+. Callers
+  # may also pass a +provider:model-id+ target or an inline configuration
+  # mapping.
   class ModelResolver
     DEFAULT_CREDENTIALS = [ # :nodoc:
       ["LITTLEGHOST_OPENROUTER_API_KEY", "openrouter"],
@@ -30,7 +40,7 @@ module LittleGhost
       @providers = providers
       @connections = providers&.connections || {}
       @profiles = normalize_profiles(profiles || {})
-      @default_model = default_model&.to_s || "default"
+      @default_model = (default_model&.to_s || "default").dup.freeze
       @provider_registry = provider_adapters.empty? ? provider_registry : ProviderRegistry.new(adapters: provider_adapters)
       @credential_resolver = credential_resolver
       configure_default_providers unless providers
@@ -254,7 +264,7 @@ module LittleGhost
 
         parent = profile["inherits"] || profile[:inherits]
         validate_role_name!(parent.to_s) if parent
-        [role, profile.to_h]
+        [role, immutable_selection_value(profile.to_h)]
       end
     end
 

data/lib/little_ghost/model_response.rb

@@ -1,11 +1,6 @@
 # frozen_string_literal: true
 
 module LittleGhost
-  # ModelResponse is the final result shared by every provider stream. It keeps
-  # provider-specific response shapes out of the agent loop.
-  #
-  # +message+ is the assistant Message, +stop_reason+ is a normalized symbol,
-  # and +usage+ contains provider-independent token counts.
   ModelResponse = Data.define(:message, :stop_reason, :usage, :metadata) do # :nodoc:
     # Creates an immutable response and coerces +message+ into a Message.
     def initialize(message:, stop_reason:, usage: Usage.new, metadata: {})
@@ -27,7 +22,7 @@ module LittleGhost
     #   new(message:, stop_reason:, usage: Usage.new, metadata: {}) -> ModelResponse
     #
     # Coerces +message+ to Message, normalizes +stop_reason+ to a Symbol, and
-    # freezes +metadata+.
+    # freezes the outer +metadata+ Hash.
 
     ##
     # :attr_reader: message
@@ -43,6 +38,7 @@ module LittleGhost
 
     ##
     # :attr_reader: metadata
-    # Frozen provider-specific response metadata.
+    # Provider-specific response metadata with a frozen outer Hash. Nested
+    # values are retained and must not be mutated by callers.
   end
 end