cline-rb 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d691efd743f7f5ed4826457a94e44d087daebb4545afad5b17b775b0fa86419
-  data.tar.gz: 49c1abc4ee95dced54956e00f30b75dc1886cf8a1e3ec35f18ff488b8972e6c1
+  metadata.gz: 5df017c7913b29844cc5cdc1611e355bcee832d6f75c09d0765a88eb9ff91b3a
+  data.tar.gz: 355b9674891ed24101c3f44d5087edf7060f33f85a8a4b010aedca55014d03b5
 SHA512:
-  metadata.gz: bec4f499ba41f796dd1e1e9f6292811854da30e9a7f8ebcf2fa9f8a87273a85908956f02ba41aba3fd9402f810c90234085690a1f7df4c46f54d8b9c7733fcf3
-  data.tar.gz: 7896bbb8e74e4efde6ea41a725df53f0e83909a2f3f7845ea86674905b43101c75452a4a78f2b2cac7ce020a4bf14f3528078fea02abda2009ea6e00523d96c3
+  metadata.gz: 918c2580895ea328088cf37bd92214c510417a7c457d6fc12e2826a807eaedb6800ae1b24c87064c7103defa61fe9d8ca042f1e8aae0ff0a2aad9bf680167c4e
+  data.tar.gz: bd0abcf30c86ed77861df47ab3c46d6ccee9348ff17b5662c431ae9c515f69478f863367e17baf7a12f63535585f246d975c1d87f55cf97e9c5aed0f000ae17f

data/CHANGELOG.md

@@ -1,3 +1,20 @@
+# [v2.3.0](https://github.com/Muriel-Salvan/cline-rb/compare/v2.2.0...v2.3.0) (2026-11-04 15:21:27)
+
+## Global changes
+### Patches
+
+* [feat(cline): add LenientSchema for tolerant deserialization of session messages's input](https://github.com/Muriel-Salvan/cline-rb/commit/a033d62989c22876030742c5e4979dc7a02bee16)
+
+## Changes for cline
+### Features
+
+* [feat(cline): add LenientSchema for tolerant deserialization of session messages's input](https://github.com/Muriel-Salvan/cline-rb/commit/a033d62989c22876030742c5e4979dc7a02bee16)
+
+## Changes for schema
+### Features
+
+* [feat(cline): add LenientSchema for tolerant deserialization of session messages's input](https://github.com/Muriel-Salvan/cline-rb/commit/a033d62989c22876030742c5e4979dc7a02bee16)
+
 # [v2.2.0](https://github.com/Muriel-Salvan/cline-rb/compare/v2.1.1...v2.2.0) (2026-11-03 16:44:07)
 
 ## Global changes

data/README.md

@@ -592,7 +592,7 @@ msg.usage         #=> Usage struct (cost, tokens)
 msg.to_human      #=> human-friendly string (limited to 128 chars by default)
 ```
 
-Contains nested schemas: `ModelInfo`, `Metrics`, `MessageContent`, `ToolUseInput`.
+Contains nested schemas: `ModelInfo`, `Metrics`, `MessageContent`, `ToolUseInput`, `ToolResultContent`.
 
 ---
 
@@ -877,6 +877,7 @@ Every domain object (settings, providers, sessions, tasks...) extends `Cline::Sc
 - **Declarative attributes** — `attribute :my_field, :string` mirrors the JSON schema.
 - **Automatic camelCase↔snake_case mapping** — Cline stores `autoUpdateEnabled`, Ruby gets `auto_update_enabled`.
 - **Extra attribute preservation** — unknown JSON keys are stored in `extra_attributes` and re-serialized back, maintaining round-trip fidelity.
+- **Typed containers & unions** — `Utils::Schema.collection(Type)` models arrays, `Utils::Schema.map(:string)` dynamic-key maps and `Utils::Schema.union(:string, Utils::Schema.collection(Type))` attributes that can be of several types.
 
 3 mixin modules handle file persistence — classes include them to "come alive" from disk:
 

data/lib/cline/lenient_schema.rb

@@ -0,0 +1,116 @@
+module Cline
+  # Base class for schemas whose data may not respect the expected types on deserialization.
+  # This is typically the case for attributes filled by an LLM, whose types are not guaranteed
+  # by the Cline CLI (for example a String given where an Array is expected).
+  #
+  # Contrary to {Schema}, deserialization does not raise exceptions for such wrong data:
+  # a warning is emitted, every attribute that can be deserialized properly is set on the instance,
+  # and the other attributes are stored in {#wrong_attributes}, keyed by their attribute name.
+  #
+  # @example
+  #   input = Cline::SessionMessage::MessageContent::ToolUseInput.of_hash(
+  #     'question' => 'Continue?',
+  #     'files' => 'not-an-array'
+  #   )
+  #   input.question          #=> 'Continue?'
+  #   input.files             #=> nil
+  #   input.wrong_attributes  #=> { files: 'not-an-array' }
+  class LenientSchema < Schema
+    extend Utils::Logger
+
+    # @!group Public API
+
+    # The attributes that could not be deserialized, keyed by their attribute name, with their raw value.
+    # Only set when at least one attribute could not be deserialized.
+    # When the whole value is not a Hash, it is stored under the '_raw' key.
+    #
+    # @return [Hash{Symbol => Object}, nil] The wrong attributes, or nil if deserialization succeeded
+    attr_accessor :wrong_attributes
+
+    class << self
+      # @!group Internal
+
+      # Cast an input value to this Schema object.
+      # Any value that cannot be cast is turned into an empty instance with {#wrong_attributes} set,
+      # instead of raising an exception.
+      #
+      # @param value [Schema, Hash, nil] The value that could be used to initialize a new instance of this attribute
+      # @return [Schema, nil] The corresponding instance, or nil if none
+      def cast(value)
+        super
+      rescue StandardError => e
+        # TODO: Make this a warn message when logger will be implemented properly
+        log_debug "!!! Cline: Unable to cast a #{value.class} into a #{name} (#{e.class}: #{e.message}). Raw value: #{value.to_s[0, 256]}"
+        instance = new
+        instance.wrong_attributes = { '_raw' => value.to_s }
+        instance
+      end
+
+      # Parse a Hash object and instantiate the proper instance from it.
+      # Instead of raising an exception when an attribute cannot be deserialized
+      # (wrong type, wrong structure...), this attribute is left unset and its raw value
+      # is stored in {#wrong_attributes}, while a warning is emitted.
+      # Attributes that can be deserialized properly are still set on the instance.
+      #
+      # @param hash [Hash] Data
+      # @param args [Array] Remaining arguments to be transferred to Shale
+      # @param kwargs [Hash] Remaining kwargs to be transferred to Shale
+      # @return [LenientSchema] Corresponding instance
+      def of_hash(hash, *args, **kwargs)
+        complete_hash_mapping
+        instance = new
+        unless hash.is_a?(Hash)
+          # TODO: Make this a warn message when logger will be implemented properly
+          log_debug "Cline: Unable to deserialize a #{name} from a #{hash.class}. Raw value: #{hash.to_s[0, 256]}"
+          instance.wrong_attributes = { '_raw' => hash.to_s }
+          return instance
+        end
+        mappings = hash_mapping.keys
+        wrong_attributes = {}
+        hash.each do |key, value|
+          mapping = mappings[key]
+          if mapping.nil?
+            # Keep unknown attributes for round-trip fidelity, as Schema does
+            (instance.extra_attributes ||= {})[key] = value
+            next
+          end
+          begin
+            set_attribute_from_hash(instance, mapping, value, *args, **kwargs)
+          rescue StandardError => e
+            # TODO: Make this a warn message when logger will be implemented properly
+            log_debug "Cline: Unable to deserialize attribute #{key.inspect} of #{name} (#{e.class}: #{e.message}). Raw value: #{value.to_s[0, 256]}"
+            wrong_attributes[mapping.attribute] = value
+          end
+        end
+        instance.wrong_attributes = wrong_attributes unless wrong_attributes.empty?
+        instance
+      end
+
+      private
+
+      # Set one attribute of an instance from its Hash value, mirroring Shale's own of_hash logic.
+      #
+      # @param instance [LenientSchema] The instance to set the attribute on
+      # @param mapping [Shale::Mapping::Descriptor::Dict] The hash mapping of the attribute
+      # @param value [Object] The raw value to deserialize
+      # @param args [Array] Remaining arguments to be transferred to Shale
+      # @param kwargs [Hash] Remaining kwargs to be transferred to Shale
+      # @return [void]
+      def set_attribute_from_hash(instance, mapping, value, *args, **kwargs)
+        attribute = attributes[mapping.attribute]
+        check_scalar_value!(attribute, value)
+        casted_value =
+          if value.nil?
+            nil
+          elsif attribute.collection?
+            (value.is_a?(Array) ? value : [value]).map do |element|
+              element.nil? ? nil : attribute.type.cast(attribute.type.of_hash(element, *args, **kwargs))
+            end
+          else
+            attribute.type.cast(attribute.type.of_hash(value, *args, **kwargs))
+          end
+        instance.send(attribute.setter, casted_value)
+      end
+    end
+  end
+end

data/lib/cline/schema.rb

@@ -10,6 +10,8 @@ module Cline
   class Schema < Shale::Mapper
     # @!group Internal
 
+    include Utils::Logger
+
     # @return [Hash] Store all extra values from a JSON parse
     attr_accessor :extra_attributes
 
@@ -23,6 +25,31 @@ module Cline
         @snake_attributes.uniq!
       end
 
+      # Enable strict type checks on deserialization.
+      # When enabled, a scalar attribute that receives an Array or a Hash raises a TypeError
+      # instead of being silently coerced.
+      #
+      # @return [void]
+      def strict_types!
+        @strict_types = true
+      end
+
+      # Are strict type checks enabled on deserialization?
+      #
+      # @return [Boolean] true if strict type checks are enabled
+      def strict_types?
+        @strict_types == true
+      end
+
+      # Check if a raw value can be deserialized by this schema.
+      # By default a schema is deserialized from a Hash, or from an instance of itself.
+      #
+      # @param raw_value [Object] The raw value to check
+      # @return [Boolean] true if {of_hash} can deserialize this value
+      def accepts_value?(raw_value)
+        raw_value.is_a?(self) || raw_value.is_a?(Hash)
+      end
+
       # Parse a Hash object and instantiate the proper instance from it.
       #
       # @param hash [Hash] Data
@@ -42,6 +69,7 @@ module Cline
             extra_hash[key] = value
           end
         end
+        validate_scalar_types!(known_hash) if strict_types?
         # Give Shale the data it knows about, without extra attributes
         instance = super(known_hash, *args, **kwargs)
         instance.extra_attributes = extra_hash unless extra_hash.empty?
@@ -81,6 +109,30 @@ module Cline
 
       private
 
+      # Validate that scalar attributes do not receive a structured value.
+      #
+      # @param known_hash [Hash] The known attributes to validate
+      # @return [void]
+      def validate_scalar_types!(known_hash)
+        known_hash.each do |key, value|
+          attribute = attributes[hash_mapping.keys[key].attribute]
+          check_scalar_value!(attribute, value) if attribute
+        end
+      end
+
+      # Check that a value is structurally compatible with an attribute.
+      # A scalar attribute should not receive an Array or a Hash.
+      #
+      # @param attribute [Shale::Attribute] The attribute to check
+      # @param value [Object] The raw value to check
+      # @return [void]
+      def check_scalar_value!(attribute, value)
+        return if value.nil? || attribute.collection? || attribute.type < Shale::Type::Complex
+        return unless value.is_a?(Array) || value.is_a?(Hash)
+
+        raise TypeError, "Attribute #{attribute.name.inspect} of #{name} expects a scalar value but got a #{value.class}"
+      end
+
       # Complete the hash mapping to include camelCase to snake_case as the defaults.
       # Do it only once.
       def complete_hash_mapping

data/lib/cline/session_message.rb

@@ -46,13 +46,18 @@ module Cline
       # @!group Public API
 
       # An input used for tool use content.
-      class ToolUseInput < Schema
+      # Its values are filled by the LLM, whose types are not guaranteed by the Cline CLI:
+      # deserialization is therefore lenient (wrong values do not raise but are stored in {#wrong_attributes}).
+      class ToolUseInput < LenientSchema
         # @!group Public API
 
         # A file to be read by the read_files tool
+        # The path is expected to be a String: a wrong type (e.g. an Array) is reported as a deserialization error.
         class FileInput < Schema
           # @!group Public API
 
+          strict_types!
+
           # @return [String] File path
           attribute :path, :string
         end
@@ -81,6 +86,27 @@ module Cline
         cline_snake_attributes :new_text, :old_text
       end
 
+      # A content entry of a tool result that is not a plain String.
+      class ToolResultContent < Schema
+        # @!group Public API
+
+        # @return [String, nil] Query or command executed by the tool
+        attribute :query, :string
+
+        # @return [String, nil] Result of the query or command
+        attribute :result, :string
+
+        # @return [Boolean, nil] Whether the query or command succeeded
+        attribute :success, :boolean
+
+        # Get a human-readable representation of this tool result.
+        #
+        # @return [String] The result of the tool, or its query if there is no result
+        def to_s
+          result || query || ''
+        end
+      end
+
       # @return [String] Content block type (text, tool_use, tool_result)
       attribute :type, :string
 
@@ -102,8 +128,8 @@ module Cline
       # @return [String, nil] Tool use identifier this result corresponds to (for type "tool_result")
       attribute :tool_use_id, :string
 
-      # @return [String, nil] Content of the tool result (for type "tool_result")
-      attribute :content, :string
+      # @return [String, Array<ToolResultContent>, nil] Content of the tool result (for type "tool_result")
+      attribute :content, Utils::Schema.union(:string, Utils::Schema.collection(ToolResultContent))
 
       cline_snake_attributes :tool_use_id
     end
@@ -169,7 +195,7 @@ module Cline
             "Assistant: #{first_text}"
           end
         when 'tool'
-          "Tool result: #{content.find { |c| c.type == 'tool_result' }&.content}"
+          "Tool result: #{human_tool_result}"
         else
           to_s
         end
@@ -202,5 +228,15 @@ module Cline
     def first_text
       content.find { |c| c.type == 'text' }&.text.to_s.gsub("\n", ' ')
     end
+
+    # Get a human representation of the tool result content of this message.
+    #
+    # @return [String] The tool result content, as a String
+    def human_tool_result
+      tool_result = content.find { |c| c.type == 'tool_result' }&.content
+      return tool_result.to_s if tool_result.nil? || tool_result.is_a?(String)
+
+      Array(tool_result).join(' ')
+    end
   end
 end

data/lib/cline/utils/schema.rb

@@ -74,6 +74,14 @@ module Cline
                 subclass.value_type = value_type
               end
 
+              # Check if a raw value can be deserialized by this map.
+              #
+              # @param raw_value [Object] The raw value to check
+              # @return [Boolean] true if this map can deserialize this value
+              def accepts_value?(raw_value)
+                raw_value.is_a?(self) || raw_value.is_a?(Hash)
+              end
+
               # Parse a Hash object and instantiate the proper instance from it.
               #
               # @param hash [Hash] Data
@@ -233,6 +241,14 @@ module Cline
                 subclass.value_type = value_type
               end
 
+              # Check if a raw value can be deserialized by this collection.
+              #
+              # @param raw_value [Object] The raw value to check
+              # @return [Boolean] true if this collection can deserialize this value
+              def accepts_value?(raw_value)
+                raw_value.is_a?(self) || raw_value.is_a?(Array)
+              end
+
               # Parse a Ruby object and instantiate the proper instance from it.
               #
               # @param hash [Object] Data
@@ -285,6 +301,145 @@ module Cline
         end
         Schema.const_get(external_name)
       end
+
+      # Provide a class that can be used by Shale for attributes that can be of several types, like this:
+      #   "content": "Some text"                  # A String
+      #   "content": [{ "query": "ls" }, ...]     # An Array of structures
+      # The first type accepting a value is used to deserialize / serialize it.
+      #
+      # @param shale_types [Array<Symbol, Class>] The Shale types this attribute can be (at least 2)
+      # @return [Class] Class that can be used in an attribute declaration
+      def self.union(*shale_types)
+        Union.of(*shale_types)
+      end
+
+      # Handle union types: attributes that can be of several types.
+      # Used by {Cline::Utils::Schema.union}.
+      class Union
+        # @!group Internal
+
+        # Ruby classes that can be deserialized by each scalar Shale type.
+        # Shale types not listed here are considered to accept any value.
+        SCALAR_VALUE_CLASSES = {
+          Shale::Type::String => String,
+          Shale::Type::Integer => Integer,
+          Shale::Type::Float => Float,
+          Shale::Type::Boolean => [TrueClass, FalseClass],
+          Shale::Type::Date => Date,
+          Shale::Type::Time => Time,
+          Shale::Type::Decimal => BigDecimal
+        }.freeze
+
+        class << self
+          # Build (or retrieve) the type class for a union of the given types.
+          #
+          # @param shale_types [Array<Symbol, Class>] The Shale types this union can be (at least 2)
+          # @return [Class] Class that can be used in an attribute declaration
+          def of(*shale_types)
+            raise ArgumentError, "A union type needs at least 2 types, got #{shale_types.size}" if shale_types.size < 2
+
+            shale_types = shale_types.map { |shale_type| shale_type.is_a?(Symbol) ? Shale::Type.lookup(shale_type) : shale_type }
+            # Give a name to this class because Shale needs it to reference it in its accessors.
+            # That also allows us to not redefine the same class several times.
+            external_name = :"UnionOf#{shale_types.map { |shale_type| shale_type.to_s.gsub(':', '') }.join('Or')}"
+            unless Cline::Utils::Schema.const_defined?(external_name)
+              union_class = new_union_class
+              union_class.union_types = shale_types
+              union_class.external_name = external_name
+              Cline::Utils::Schema.const_set(external_name, union_class)
+            end
+            Cline::Utils::Schema.const_get(external_name)
+          end
+
+          # Check if a raw value can be deserialized by a given Shale type.
+          # Shale types that don't handle accepted values are considered as scalar types.
+          #
+          # @param shale_type [Class] The Shale type to check
+          # @param raw_value [Object] The raw value to check
+          # @return [Boolean] true if the Shale type can deserialize this value
+          def accepts_value?(shale_type, raw_value)
+            if shale_type.respond_to?(:accepts_value?)
+              shale_type.accepts_value?(raw_value)
+            else
+              raw_value.is_a?(SCALAR_VALUE_CLASSES.fetch(shale_type, Object))
+            end
+          end
+
+          private
+
+          # Create the class implementing a union type.
+          #
+          # @return [Class] The new union type class
+          def new_union_class
+            Class.new(Cline::Schema) do
+              class << self
+                attr_accessor :union_types, :external_name
+
+                # Check if a raw value can be deserialized by one of this union's types.
+                #
+                # @param raw_value [Object] The raw value to check
+                # @return [Boolean] true if one of this union's types accepts this value
+                def accepts_value?(raw_value)
+                  raw_value.is_a?(self) ||
+                    union_types.any? { |union_type| Cline::Utils::Schema::Union.accepts_value?(union_type, raw_value) }
+                end
+
+                # Parse a value and instantiate the proper instance from it.
+                #
+                # @param value [Object] Data
+                # @param args [Array] Remaining arguments to be transferred to Shale
+                # @param kwargs [Hash] Remaining kwargs to be transferred to Shale
+                # @return [Object, nil] Corresponding instance, or nil if value is nil
+                def of_hash(value, *args, **kwargs)
+                  return nil if value.nil?
+
+                  union_type_for(value).of_hash(value, *args, **kwargs)
+                end
+
+                # Get a Ruby object from an instance.
+                #
+                # @param value [Object] Object to serialize
+                # @param args [Array] Remaining arguments to be transferred to Shale
+                # @param kwargs [Hash] Remaining kwargs to be transferred to Shale
+                # @return [Object, nil] Corresponding Ruby object, or nil if value is nil
+                def as_hash(value, *args, **kwargs)
+                  return nil if value.nil?
+
+                  union_type_for(value).as_hash(value, *args, **kwargs)
+                end
+
+                # Cast an input value to the type matching it.
+                #
+                # @param value [Object, nil] The value to cast
+                # @return [Object, nil] The corresponding instance, or nil if none
+                def cast(value)
+                  return nil if value.nil?
+
+                  union_type_for(value).cast(value)
+                end
+
+                # Return the class name
+                #
+                # @return [String] The class name
+                def to_s
+                  "::Cline::Utils::Schema::#{@external_name}"
+                end
+
+                private
+
+                # Get the type that can deserialize / serialize a given value.
+                #
+                # @param value [Object] The value to find the type of
+                # @return [Class] The corresponding type
+                def union_type_for(value)
+                  union_types.find { |union_type| Cline::Utils::Schema::Union.accepts_value?(union_type, value) } ||
+                    raise("Unable to cast a #{value.class} into #{name}")
+                end
+              end
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/cline/version.rb

@@ -2,5 +2,5 @@ module Cline
   # @!group Public API
 
   # Gem version
-  VERSION = '2.2.0'
+  VERSION = '2.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cline-rb
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.0
 platform: ruby
 authors:
 - Muriel Salvan
@@ -187,6 +187,7 @@ files:
 - lib/cline/global_state/models.rb
 - lib/cline/global_state/toggles.rb
 - lib/cline/global_state/workspace.rb
+- lib/cline/lenient_schema.rb
 - lib/cline/log.rb
 - lib/cline/logs.rb
 - lib/cline/mcp_settings.rb