cline-rb 1.0.0

data/lib/cline/task.rb

@@ -0,0 +1,75 @@
+module Cline
+  # A task defined in a directory
+  class Task
+    # @!group Public API
+
+    include Serializable::Dir
+
+    # Get the task's messages
+    #
+    # @param create [Boolean] Should the data be created if it does not exist?
+    # @return [TaskMessages, nil] The task's messages, or nil if none
+    def messages(create: self.create)
+      @messages ||= TaskMessages.from_cline_data(dir, cline_models: @cline_models, create:)
+    end
+
+    # Equality check
+    #
+    # @param other [Object] The other to check equality with
+    # @return [Boolean] True if objects are equal
+    def ==(other)
+      other.is_a?(Task) &&
+        other.messages == messages
+    end
+
+    # Monitor messages with a callback called when new or updated messages arrive
+    #
+    # @param on_message [#call] Block called each time there is a new or updated message.
+    #   * Param message [TaskMessage] Message that has happened
+    #   * Param last [Boolean] Is this the last message fetched from the list of messages?
+    #   * Param previous_version [TaskMessage or nil] Previous version of this message if it got updated, or nil if it is a new one
+    # @param ignore_partials [Boolean] Should we ignore partial messages?
+    #   If true, then on_message will only be called for messages that have been fully received.
+    # @param monitoring_interval_secs [Float] The monitoring interval in seconds
+    # @yield Optional code called while monitoring is in place.
+    #   If used then monitoring is stopped at the end of the block's execution.
+    # @return [FileMonitor, nil] If no block has been given, return the monitor that needs to be
+    #   stopped by the caller when monitoring should end.
+    def monitor_messages(on_message:, ignore_partials: false, monitoring_interval_secs: 1, &)
+      # Keep messages per timestamp to detect updates
+      messages = {}
+      TaskMessages.monitor_cline_data_changes(
+        dir,
+        cline_models: @cline_models,
+        on_change: proc do |new_messages|
+          # Update the messages we have
+          @messages = new_messages
+          if new_messages && !new_messages.empty?
+            # Filter unwanted messages
+            new_messages = new_messages.reject(&:partial) if ignore_partials
+            # Check for updates in all messages
+            last_idx = new_messages.size - 1
+            new_messages.each.with_index do |message, idx|
+              ts = message.ts
+              if message != messages[ts]
+                on_message.call(message, idx == last_idx, messages[ts])
+                messages[ts] = message
+              end
+            end
+          end
+        end,
+        monitoring_interval_secs:,
+        &
+      )
+    end
+
+    # @!group Internal
+
+    # Constructor
+    #
+    # @param cline_models [Models] The Cline models used to interpret the tasks' messages
+    def initialize(cline_models:)
+      @cline_models = cline_models
+    end
+  end
+end

data/lib/cline/task_message.rb

@@ -0,0 +1,247 @@
+require 'ellipsized'
+require 'time'
+
+module Cline
+  # Task's message
+  class TaskMessage < Schema
+    # @!group Public API
+
+    # Model info in messages
+    class ModelInfo < Schema
+      # @!group Public API
+
+      # @return [String] Provider
+      attribute :provider_id, :string
+
+      # @return [String] Model
+      attribute :model_id, :string
+
+      # @return [String] Mode (plan or act)
+      attribute :mode, :string
+    end
+
+    # @return [Integer] Message timestamp
+    attribute :ts, :integer
+
+    # @return [String] Message type identifier
+    attribute :type, :string
+
+    # @return [String] Say message identifier
+    attribute :say, :string
+
+    # @return [String] Ask message identifier
+    attribute :ask, :string
+
+    # @return [String] Raw text content of the message
+    attribute :text, :string
+
+    # @return [ModelInfo] Model metadata
+    attribute :model_info, ModelInfo
+
+    # @return [Integer] Position index within the conversation history sequence
+    attribute :conversation_history_index, :integer
+
+    # @return [Boolean] Flag indicating this is an incomplete streaming message
+    attribute :partial, :boolean
+
+    # Get the message timestamp as a Ruby time
+    #
+    # @return [Time] The message timestamp
+    def timestamp
+      @timestamp ||= Time.at(ts / 1000.0)
+    end
+
+    # Get the usage statistics of this message, if any
+    #
+    # @return [Usage, nil] The usage statistics, or nil if none
+    def usage
+      return unless type == 'say' && say == 'api_req_started'
+
+      api_details = JSON.parse(text, symbolize_names: true)
+      Usage.new(
+        **{
+          cost: api_details[:cost],
+          input_tokens: api_details[:tokensIn],
+          output_tokens: api_details[:tokensOut],
+          cache_read_tokens: api_details[:cacheReads],
+          cache_write_tokens: api_details[:cacheWrites],
+          cline_model: cline_models[model_info.model_id]
+        }.compact
+      )
+    end
+
+    # Return a human-friendly version of a message.
+    # Useful for stdout or logging.
+    #
+    # @param limit [Integer] Number of characters the message should be limited to
+    # @return [String] The human translation
+    def to_human(limit: 128)
+      case type
+      when 'say'
+        case say
+        when 'text', 'task'
+          one_lining(text)
+        when 'api_req_started'
+          sections = parse_sections(JSON.parse(text, symbolize_names: true)[:request])
+          section_delimiter = '|'
+          # Ignore some sections
+          sections.reject! { |section| section[:name] == 'environment_details' }
+          section_size = (limit / sections.size) - section_delimiter.size
+          sections.map do |section|
+            "#{"#{section[:name]}: " if section[:name]}#{one_lining(section[:content])}".ellipsized(section_size)
+          end.join('|')
+        when 'tool'
+          tool_details = JSON.parse(text, symbolize_names: true)
+          tool_header =
+            case tool_details[:tool]
+            when 'readFile'
+              "[readFile] - #{tool_details[:path]}"
+            when 'listFilesRecursive'
+              "[listFilesRecursive] - #{tool_details[:path]}"
+            when 'listFilesTopLevel'
+              "[listFilesTopLevel] - #{tool_details[:path]}"
+            when 'newFileCreated'
+              "[newFileCreated] - #{tool_details[:path]}"
+            when 'editedExistingFile'
+              "[editedExistingFile] - #{tool_details[:path]}"
+            when 'searchFiles'
+              "[searchFiles] - #{tool_details[:path]} (regex: #{tool_details[:regex]})"
+            when 'useSkill'
+              "[useSkill] - #{tool_details[:skill_name]}"
+            else
+              raise NotImplementedError, "Unknown tool @ts #{ts}: #{self}"
+            end
+          "#{tool_header}#{": #{one_lining(tool_details[:content])}".ellipsized(limit - tool_header.size) if tool_details.key?(:content)}"
+        when 'api_req_retried'
+          'API request retried'
+        when 'command'
+          "Command: #{one_lining(text)}"
+        when 'command_output'
+          "Command output: #{one_lining(text)}"
+        when 'diff_error'
+          "Diff error: #{one_lining(text)}"
+        when 'error_retry'
+          "Error retry: #{one_lining(text)}"
+        when 'reasoning'
+          "Reasoning: #{one_lining(text)}"
+        when 'user_feedback'
+          "User feedback: #{one_lining(text)}"
+        when 'task_progress'
+          # Count completed vs total tasks
+          completed_tasks = text.scan('- [x]').size
+          total_tasks = text.scan(/- \[[ x]\]/).size
+          "Task progress: #{completed_tasks}/#{total_tasks} tasks"
+        when 'completion_result'
+          "Task completed: #{one_lining(text)}"
+        when 'error'
+          "Error: #{one_lining(text)}"
+        else
+          raise NotImplementedError, "Unknown say @ts #{ts}: #{self}"
+        end
+      when 'ask'
+        "Ask user: #{
+          case ask
+          when 'resume_task'
+            'Resume task'
+          when 'resume_completed_task'
+            'Resume completed task'
+          when 'api_req_failed'
+            details = JSON.parse(text, symbolize_names: true)
+            "API request failed - #{details[:code]} - #{one_lining(details[:message])}"
+          when 'command_output'
+            "Command output - #{one_lining(text)}"
+          when 'completion_result'
+            'Completion result'
+          when 'followup'
+            details = JSON.parse(text, symbolize_names: true)
+            "Follow-up - #{details[:question]}#{" - Options: #{details[:options].join(', ')}" unless details[:options].nil? || details[:options].empty?}"
+          when 'plan_mode_respond'
+            details = JSON.parse(text, symbolize_names: true)
+            "Plan mode respond - #{one_lining(details[:response])}}"
+          when 'tool'
+            details = JSON.parse(text, symbolize_names: true)
+            tool_name = details.delete(:tool)
+            "Use tool - #{tool_name} - #{JSON.dump(details)}}"
+          when 'mistake_limit_reached'
+            "Mistake limit reached - #{one_lining(text)}}"
+          when 'new_task'
+            "New task - #{one_lining(text)}"
+          else
+            raise NotImplementedError, "Unknown ask @ts #{ts}: #{self}"
+          end
+        }"
+      else
+        raise NotImplementedError, "Unknown type @ts #{ts}: #{self}"
+      end.ellipsized(limit)
+    end
+
+    # @!group Internal
+
+    # Parse a Hash object and instantiate the proper instance from it.
+    #
+    # @param hash [Hash] Data
+    # @param args [Array] Remaining arguments to be transferred to Shale
+    # @param cline_models [Models] The Clines models used to interpret the message
+    # @param kwargs [Hash] Remaining kwargs to be transferred to Shale
+    # @return [Schema] Corresponding instance
+    def self.of_hash(hash, *args, cline_models:, **kwargs)
+      instance = super(hash, *args, **kwargs)
+      instance.cline_models = cline_models
+      instance
+    end
+
+    # @return [Models] The Clines models used to interpret the message
+    attr_accessor :cline_models
+
+    private
+
+    # Convert a string to a single line by replacing newlines with spaces and removing carriage returns
+    #
+    # @param text [String] The text to convert to one line
+    # @return [String] The text converted to a single line
+    def one_lining(text)
+      text.strip.gsub("\n", ' ').gsub("\r", '')
+    end
+
+    # Use a single regex to match complete tag pairs
+    # This regex matches <tag>content</tag> patterns
+    COMPLETE_TAG_PATTERN = %r{<([a-zA-Z0-9_:]*)>(.*?)</\1>}m
+    private_constant :COMPLETE_TAG_PATTERN
+
+    # Parse sections from a string with HTML-like tags.
+    # Sections are delimited by html-like tags, for example `<toto>...</toto>` is the section named `toto`.
+    # Sections without tags should still be part of the result, with a nil section name.
+    # Only considers top-level tags (no recursion).
+    #
+    # @param content [String] The input string to parse
+    # @return [Array<Hash{Symbol => Object}>] List of sections found from the content. Each section can have the following properties:
+    #   * name [String, nil] Section name, or nil if no name was given to this section (in-between named sections).
+    #   * content [String] Section content.
+    def parse_sections(content)
+      sections = []
+      current_pos = 0
+      content_length = content.length
+      # Use cursor progression to maintain order
+      while current_pos < content_length
+        # Find the next complete tag pair starting from current position
+        match = content.match(COMPLETE_TAG_PATTERN, current_pos)
+        if match
+          # Add any untagged content before this tag
+          if match.begin(0) > current_pos
+            untagged_content = content[current_pos...match.begin(0)]
+            sections << { name: nil, content: untagged_content } unless untagged_content.strip.empty?
+          end
+          # Add the tagged section
+          sections << { name: match[1], content: match[2] }
+          current_pos = match.end(0)
+        else
+          # No more tags found, add remaining content
+          remaining_content = content[current_pos..]
+          sections << { name: nil, content: remaining_content } unless remaining_content.strip.empty?
+          current_pos = content_length
+        end
+      end
+      sections
+    end
+  end
+end

data/lib/cline/task_messages.rb

@@ -0,0 +1,11 @@
+module Cline
+  # Base class, dynamically defined
+  TaskMessageCollection = Utils::Schema.collection(TaskMessage)
+
+  # Access all messages associated to a Cline task
+  class TaskMessages < TaskMessageCollection
+    # @!group Public API
+
+    Serializable::ClineData.include_for(self, 'ui_messages.json')
+  end
+end

data/lib/cline/tasks.rb

@@ -0,0 +1,30 @@
+module Cline
+  # Provide a set of tasks from a directory
+  class Tasks
+    # @!group Public API
+
+    include Utils::EnumerableDirObjects
+
+    # @!group Internal
+
+    # Constructor
+    #
+    # @param cline_models [Models] The Cline models used to interpret the tasks' messages
+    def initialize(cline_models:)
+      @cline_models = cline_models
+    end
+
+    private
+
+    # Get an object and its name from a sub-directory
+    #
+    # @param dir [String] The directory containing the object
+    # @param create [Boolean] Should the instance be created if it does not exist?
+    # @return [Array(String, Object)] Return 2 values:
+    #   0. [String] The object name
+    #   1. [Object] The object itself
+    def object_from(dir, create:)
+      [File.basename(dir), Task.open(dir, cline_models: @cline_models, create:)]
+    end
+  end
+end

data/lib/cline/usage.rb

@@ -0,0 +1,37 @@
+module Cline
+  # Track usage statistics associated to a message
+  Usage = Struct.new(
+    # @!group Public API
+
+    # [Float] Monetary cost incurred for this API request
+    :cost,
+
+    # [Integer] Total input tokens sent in the request
+    :input_tokens,
+
+    # [Integer] Total output tokens generated in the response
+    :output_tokens,
+
+    # [Integer] Number of tokens retrieved from cache
+    :cache_read_tokens,
+
+    # [Integer] Number of tokens stored into cache
+    :cache_write_tokens,
+
+    # [Model. nil] Model used for this request, or nil if none
+    :cline_model,
+    keyword_init: true
+  ) do
+    # @!group Public API
+
+    # @return [Integer] Total context tokens consumed
+    def context_tokens
+      input_tokens + output_tokens + cache_read_tokens + cache_write_tokens
+    end
+
+    # @return [Integer, nil] Maximum context window limit for the used model
+    def context_tokens_limit
+      cline_model&.context_window
+    end
+  end
+end

data/lib/cline/utils/enumerable_dir_objects.rb

@@ -0,0 +1,103 @@
+require 'forwardable'
+
+module Cline
+  module Utils
+    # Simple mixin providing an Enumerable and Set interfaces on objects initialized from
+    #   a list of sub-directories.
+    # Classes including this mixin should call Class.open(dir) to instantiate a new instance initialized from a directory,
+    #   and implement the method object_from(dir) to return the corresponding name and object parsed from a sub-directory.
+    module EnumerableDirObjects
+      extend Forwardable
+
+      # @!group Public API
+
+      include Enumerable
+
+      # Give a Hash interface
+      def_delegators :objects_set, *%i[[] each empty? key? keys size values]
+
+      # Equality check
+      #
+      # @param other [Object] The other to check equality with
+      # @return [Boolean] True if objects are equal
+      def ==(other)
+        other.is_a?(EnumerableDirObjects) &&
+          other.size == size &&
+          other.each.to_a.to_h == each.to_a.to_h
+      end
+
+      # Create a new object from this sub-directories set.
+      # This also creates a new sub-directory.
+      #
+      # @param name [String] The object name to create (also serves as sub-directory name)
+      # @return [Object] The corresponding instance that has been setup from this new sub-directory
+      def new(name)
+        _name, instance = object_from(::File.join(dir, name), create: true)
+        objects_set[name] = instance
+        instance
+      end
+
+      # @!group Internal
+
+      # Hook used when this mixin is included in a base class
+      #
+      # @param base [Class] The base class
+      def self.included(base)
+        base.include(Serializable::Dir)
+      end
+
+      # Include the mixin and configure it for a specific object class
+      # This method automatically implements the required object_from method
+      #
+      # @param calling_class [Class] The class that is calling this method
+      # @param object_class [Class] The class to instantiate for each directory
+      def self.include_for(calling_class, object_class)
+        calling_class.class_eval do
+          include EnumerableDirObjects
+
+          private
+
+          # Get an object and its name from a sub-directory
+          #
+          # @param dir [String] The directory containing the object
+          # @param create [Boolean] Should the instance be created if it does not exist?
+          # @return [Array(String, Object)] Return 2 values:
+          #   0. [String] The object name
+          #   1. [Object] The object itself
+          define_method(:object_from) do |dir, create:|
+            [::File.basename(dir), object_class.open(dir, create:)]
+          end
+        end
+      end
+
+      # Remove caches.
+      def refresh!
+        @objects_set = nil
+      end
+
+      private
+
+      # Read all objects from the dir.
+      # Memoize it.
+      #
+      # @return [Hash{String => Object}] The objects, per object name
+      def objects_set
+        @objects_set ||= Dir
+          .glob(::File.join(dir, '*'))
+          .select { |path| ::File.directory?(path) }
+          .to_h { |subdir| object_from(subdir, create: create) }
+      end
+
+      # Get an object and its name from a sub-directory
+      #
+      # @param dir [String] The directory containing the object
+      # @param create [Boolean] Should the instance be created if it does not exist?
+      # @return [Array(String, Object)] Return 2 values:
+      #   0. [String] The object name
+      #   1. [Object] The object itself
+      def object_from(dir, create:)
+        raise NotImplementedError, 'This method should be implemented by the class including this mixin.'
+      end
+    end
+  end
+end

data/lib/cline/utils/file.rb

@@ -0,0 +1,71 @@
+require 'fileutils'
+require 'tmpdir'
+
+module Cline
+  module Utils
+    # Some file helpers
+    module File
+      # Try to read a file with retries in case other processes are using it.
+      #
+      # Parameters::
+      # * *file* (String): Path to read
+      # * *max_retries* (Integer): Number of retries in case of concurrent access [default: 3]
+      # Result::
+      # * String: The file content
+      def self.safe_read(file, max_retries: 3)
+        retries = 0
+        file_content = nil
+        begin
+          file_content = ::File.read(file)
+        rescue Errno::EACCES, Errno::EAGAIN
+          # Could be that the file is being written at the same time.
+          # Just try again.
+          retries += 1
+          raise if retries > max_retries
+
+          sleep(0.05 * retries)
+          retry
+        end
+        file_content
+      end
+
+      # Try to read a file and parse its JSON content with retries.
+      # Uses safe_read internally, and also retries on JSON parse errors
+      # (e.g. if the file was half-written when read).
+      #
+      # Parameters::
+      # * *file* (String): Path to read
+      # * *max_retries* (Integer): Number of retries for both file access and JSON parsing [default: 3]
+      # Result::
+      # * Object: The parsed JSON content
+      def self.safe_json_read(file, max_retries: 3)
+        retries = 0
+        begin
+          content = safe_read(file, max_retries: max_retries)
+          JSON.parse(content)
+        rescue JSON::ParserError
+          retries += 1
+          raise if retries > max_retries
+
+          sleep(0.05 * retries)
+          retry
+        end
+      end
+
+      # Provide a temporary directory.
+      # Will clean up the directory after code execution unless debug mode is on.
+      #
+      # @yield [temp_dir] Block called with the temp directory ready
+      # @yieldparam temp_dir [String] The temp directory
+      def self.with_temp_dir(&)
+        if Cline.config.debug
+          temp_dir = "#{Cline.config.temp_dir_root}/#{Time.now.utc.strftime('%Y-%m-%d-%H-%M-%S-%N')}"
+          FileUtils.mkdir_p temp_dir
+          yield temp_dir
+        else
+          Dir.mktmpdir(&)
+        end
+      end
+    end
+  end
+end

data/lib/cline/utils/file_monitor.rb

@@ -0,0 +1,56 @@
+module Cline
+  module Utils
+    # Provide a file changes monitor.
+    # Calls a callback as a separate thread for each change that happens on a file
+    class FileMonitor
+      # Constructor
+      #
+      # @param file [String] The file to monitor
+      # @param on_change [#call] Block called each time there is an update.
+      #   * Param mtime [Time, nil] The new file's modification time, or nil if the file is missing
+      # @param monitoring_interval_secs [Float] The monitoring interval in seconds
+      def initialize(file, on_change:, monitoring_interval_secs: 1)
+        @file = file
+        @on_change = on_change
+        @monitoring_interval_secs = monitoring_interval_secs
+        @monitoring = false
+        @monitoring_thread = nil
+      end
+
+      # Start monitoring
+      #
+      # @yield Optional block that is called while monitoring has started.
+      #   If this block is given, then #stop will be called automatically at the end of the block execution.
+      def start
+        @monitoring = true
+        @monitoring_thread = Thread.new do
+          file_mtime = nil
+          loop do
+            new_file_mtime = ::File.exist?(@file) ? ::File.mtime(@file) : nil
+            if new_file_mtime != file_mtime
+              # There is an update
+              @on_change.call(new_file_mtime)
+              file_mtime = new_file_mtime
+            end
+            break unless @monitoring
+
+            sleep @monitoring_interval_secs
+          end
+        end
+        return unless block_given?
+
+        begin
+          yield
+        ensure
+          stop
+        end
+      end
+
+      # Stop monitoring
+      def stop
+        @monitoring = false
+        @monitoring_thread.join
+      end
+    end
+  end
+end

data/lib/cline/utils/logger.rb

@@ -0,0 +1,37 @@
+require 'strings/ansi'
+
+module Cline
+  # Various internal utilities and helpers.
+  module Utils
+    # Mixin adding some debug logging capabilities
+    module Logger
+      class << self
+        # Sanitize some PTY output:
+        # - Remove ANSI escape codes.
+        # - Remove CSI escape codes.
+        # - Remove OSC escape codes.
+        #
+        # @param pty_output [String] PTY output string
+        # @param colored [Boolean] Do we keep colored output?
+        # @return [String] Resulting sanitized string
+        def sanitize_pty_output(pty_output, colored: false)
+          pty_output = Strings::ANSI.sanitize(pty_output) unless colored
+          pty_output.gsub(/\e\][^\a]*\a/, '')
+        end
+      end
+
+      # Log a message if debug was activated
+      #
+      # Parameters::
+      # @param msg [String, nil] Message to be displayed, or nil if the message is given lazily through a code block
+      # @yield Code returning a String for lazy evaluation
+      #   * Return [String] Debug message
+      def log_debug(msg = nil)
+        return unless Cline.config.debug
+
+        msg = yield if block_given?
+        puts "[CLINE DEBUG] - #{msg}"
+      end
+    end
+  end
+end