cline-rb 1.0.0

data/lib/cline/session.rb

@@ -0,0 +1,87 @@
+require 'forwardable'
+
+module Cline
+  # A session defined in a directory
+  class Session
+    extend Forwardable
+
+    # @!group Public API
+
+    include Serializable::Dir
+
+    # Delegates all data attributes to the data object
+    def_delegators :data, *SessionData.attributes.keys
+
+    # Get the session's data
+    #
+    # @param create [Boolean] Should the data be created if it does not exist?
+    # @return [SessionData, nil] The session's data, or nil if none
+    def data(create: self.create)
+      @data ||= SessionData.from_cline_data(dir, create:)
+    end
+
+    # Get the session's messages
+    #
+    # @param create [Boolean] Should the messages be created if they don't exist?
+    # @return [SessionMessages, nil] The session's messages, or nil if none
+    def messages(create: self.create)
+      @messages ||= SessionMessages.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?(Session) &&
+        other.data == data &&
+        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 [SessionMessage] Message that has happened
+    #   * Param last [Boolean] Is this the last message fetched from the list of messages?
+    #   * Param previous_version [SessionMessage or nil] Previous version of this message if it got updated, or nil if it is a new one
+    # @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:, monitoring_interval_secs: 1, &)
+      # Keep messages per timestamp to detect updates
+      messages = {}
+      SessionMessages.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&.messages && !new_messages.messages.empty?
+            # Check for updates in all messages
+            last_idx = new_messages.messages.size - 1
+            new_messages.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/session_data.rb

@@ -0,0 +1,154 @@
+module Cline
+  # Session data
+  class SessionData < Schema
+    # @!group Public API
+
+    Serializable::ClineData.include_for(self, proc { |base_dir| "#{File.basename(base_dir)}.json" })
+
+    # Session metadata
+    class Metadata < Schema
+      # @!group Public API
+
+      # Checkpoint metadata
+      class Checkpoint < Schema
+        # @!group Public API
+
+        # Checkpoint entry (ref, timestamps, etc.)
+        class CheckpointEntry < Schema
+          # @!group Public API
+
+          # @return [String] Git ref of the checkpoint
+          attribute :ref, :string
+
+          # @return [Integer] Timestamp when the checkpoint was created
+          attribute :created_at, :integer
+
+          # @return [Integer] Number of runs for this checkpoint
+          attribute :run_count, :integer
+
+          # @return [String] Kind of checkpoint (e.g. "stash")
+          attribute :kind, :string
+        end
+
+        # @return [CheckpointEntry] Latest checkpoint entry
+        attribute :latest, CheckpointEntry
+
+        # @return [Array<CheckpointEntry>] History of checkpoint entries
+        attribute :history, Utils::Schema.collection(CheckpointEntry)
+      end
+
+      # Usage statistics
+      class Usage < Schema
+        # @!group Public API
+
+        # @return [Integer] Input tokens count
+        attribute :input_tokens, :integer
+
+        # @return [Integer] Output tokens count
+        attribute :output_tokens, :integer
+
+        # @return [Integer] Cache read tokens count
+        attribute :cache_read_tokens, :integer
+
+        # @return [Integer] Cache write tokens count
+        attribute :cache_write_tokens, :integer
+
+        # @return [Float] Total cost of the API call
+        attribute :total_cost, :float
+      end
+
+      # @return [Checkpoint] Checkpoint information
+      attribute :checkpoint, Checkpoint
+
+      # @return [String] Title of the session
+      attribute :title, :string
+
+      # @return [Float] Total cost of the session
+      attribute :total_cost, :float
+
+      # @return [Float] Aggregated agents cost
+      attribute :aggregated_agents_cost, :float
+
+      # @return [Usage] Usage statistics
+      attribute :usage, Usage
+
+      # @return [Usage] Aggregate usage statistics
+      attribute :aggregate_usage, Usage
+    end
+
+    # @return [Integer] Version number
+    attribute :version, :integer
+
+    # @return [String] Unique session identifier
+    attribute :session_id, :string
+
+    # @return [String] Source of the session (e.g. "cli")
+    attribute :source, :string
+
+    # @return [Integer] Process ID
+    attribute :pid, :integer
+
+    # @return [String] Start time of the session (ISO 8601)
+    attribute :started_at, :string
+
+    # @return [String] End time of the session (ISO 8601)
+    attribute :ended_at, :string
+
+    # @return [Integer] Exit code of the process
+    attribute :exit_code, :integer
+
+    # @return [String] Session status (e.g. "completed")
+    attribute :status, :string
+
+    # @return [Boolean] Whether the session is interactive
+    attribute :interactive, :boolean
+
+    # @return [String] Provider name (e.g. "cline")
+    attribute :provider, :string
+
+    # @return [String] Model name (e.g. "deepseek/deepseek-v4-flash")
+    attribute :model, :string
+
+    # @return [String] Current working directory
+    attribute :cwd, :string
+
+    # @return [String] Workspace root path
+    attribute :workspace_root, :string
+
+    # @return [String] Team name
+    attribute :team_name, :string
+
+    # @return [Boolean] Whether tools are enabled
+    attribute :enable_tools, :boolean
+
+    # @return [Boolean] Whether spawn is enabled
+    attribute :enable_spawn, :boolean
+
+    # @return [Boolean] Whether teams are enabled
+    attribute :enable_teams, :boolean
+
+    # @return [String] Prompt for the session
+    attribute :prompt, :string
+
+    # @return [Metadata] Session metadata
+    attribute :metadata, Metadata
+
+    # @return [String] Path to the messages file
+    attribute :messages_path, :string
+
+    cline_snake_attributes(
+      *%i[
+        session_id
+        started_at
+        ended_at
+        exit_code
+        workspace_root
+        team_name
+        enable_tools
+        enable_spawn
+        enable_teams
+        messages_path
+      ]
+    )
+  end
+end

data/lib/cline/session_message.rb

@@ -0,0 +1,178 @@
+require 'ellipsized'
+require 'time'
+
+module Cline
+  # Session's message
+  class SessionMessage < Schema
+    # @!group Public API
+
+    # Model info in session messages
+    class ModelInfo < Schema
+      # @!group Public API
+
+      # @return [String] Model ID
+      attribute :id, :string
+
+      # @return [String] Provider
+      attribute :provider, :string
+
+      # @return [String] Model family
+      attribute :family, :string
+    end
+
+    # Metrics in session messages
+    class Metrics < Schema
+      # @!group Public API
+
+      # @return [Integer] Input tokens count
+      attribute :input_tokens, :integer
+
+      # @return [Integer] Output tokens count
+      attribute :output_tokens, :integer
+
+      # @return [Integer] Cache read tokens count
+      attribute :cache_read_tokens, :integer
+
+      # @return [Integer] Cache write tokens count
+      attribute :cache_write_tokens, :integer
+
+      # @return [Float] Cost of the API call
+      attribute :cost, :float
+    end
+
+    # A content block in a session message.
+    # All attributes are optional, some will be nil depending on the type of content.
+    class MessageContent < Schema
+      # @!group Public API
+
+      # An input used for tool use content.
+      class ToolUseInput < Schema
+        # @!group Public API
+
+        # @return [String] Question
+        attribute :question, :string
+
+        # @return [Array<String>] List of options for the given question
+        attribute :options, Utils::Schema.collection(:string)
+      end
+
+      # @return [String] Content block type (text, tool_use, tool_result)
+      attribute :type, :string
+
+      # @return [String, nil] Text content (for type "text")
+      attribute :text, :string
+
+      # @return [String, nil] Tool use identifier (for type "tool_use")
+      attribute :id, :string
+
+      # @return [String, nil] Tool name (for type "tool_use")
+      attribute :name, :string
+
+      # @return [ToolUseInput, nil] Tool input parameters (for type "tool_use")
+      attribute :input, ToolUseInput
+
+      # @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
+
+      cline_snake_attributes :tool_use_id
+    end
+
+    # @return [String] Message identifier
+    attribute :id, :string
+
+    # @return [String] Role (user or assistant)
+    attribute :role, :string
+
+    # @return [Array<MessageContent>] Content blocks
+    attribute :content, Utils::Schema.collection(MessageContent)
+
+    # @return [Integer] Message timestamp in milliseconds
+    attribute :ts, :integer
+
+    # @return [ModelInfo, nil] Model metadata
+    attribute :model_info, ModelInfo
+
+    # @return [Metrics, nil] Usage metrics
+    attribute :metrics, Metrics
+
+    # 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 metrics
+
+      @usage ||= Usage.new(
+        **{
+          cost: metrics.cost,
+          input_tokens: metrics.input_tokens,
+          output_tokens: metrics.output_tokens,
+          cache_read_tokens: metrics.cache_read_tokens,
+          cache_write_tokens: metrics.cache_write_tokens,
+          cline_model: cline_models && cline_models[model_info.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 role
+        when 'user'
+          "User: #{first_text}"
+        when 'assistant'
+          tool_use = content.find { |c| c.type == 'tool_use' }
+          if tool_use
+            "Assistant uses #{tool_use.name}"
+          else
+            "Assistant: #{first_text}"
+          end
+        when 'tool'
+          "Tool result: #{content.find { |c| c.type == 'tool_result' }&.content}"
+        else
+          to_s
+        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, nil] The Clines models used to interpret the message, or nil if none
+    # @param kwargs [Hash] Remaining kwargs to be transferred to Shale
+    # @return [Schema] Corresponding instance
+    def self.of_hash(hash, *args, cline_models: nil, **kwargs)
+      instance = super(hash, *args, **kwargs)
+      instance.cline_models = cline_models if cline_models
+      instance
+    end
+
+    # @return [Models] The Clines models used to interpret the message
+    attr_accessor :cline_models
+
+    private
+
+    # Get the text from the first text content block.
+    #
+    # @return [String] The first text content, or an empty string if none
+    def first_text
+      content.find { |c| c.type == 'text' }&.text.to_s.gsub("\n", ' ')
+    end
+  end
+end

data/lib/cline/session_messages.rb

@@ -0,0 +1,61 @@
+require 'forwardable'
+
+module Cline
+  # Session messages
+  class SessionMessages < Schema
+    extend Forwardable
+
+    # @!group Public API
+
+    Serializable::ClineData.include_for(self, proc { |base_dir| "#{File.basename(base_dir)}.messages.json" })
+
+    # @return [Integer] Schema version
+    attribute :version, :integer
+
+    # @return [String] Last update timestamp of this messages file
+    attribute :updated_at, :string
+
+    # @return [String] Agent identifier (lead or agent)
+    attribute :agent, :string
+
+    # @return [String] Session ID
+    attribute :session_id, :string
+
+    # @return [Array<SessionMessage>] Messages of this session
+    attribute :messages, Utils::Schema.collection(SessionMessage)
+
+    # @return [String] System prompt used for this session
+    attribute :system_prompt, :string
+
+    cline_snake_attributes(*%i[updated_at system_prompt])
+
+    # Delegates enumerating methods to the internal messages
+    def_delegators :wrapped_messages, *%i[[] << each empty? last size]
+
+    include Enumerable
+
+    # @!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 Cline models used to interpret the tasks' messages
+    # @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)
+      # Shale doesn't pass extra kwargs to nested collection items,
+      # so we set cline_models on each message after deserialization
+      instance.messages&.each { |message| message.cline_models = cline_models }
+      instance
+    end
+
+    # Return the messages as an array, even if there are no message.
+    #
+    # @return [Array] The messages
+    def wrapped_messages
+      messages || []
+    end
+  end
+end

data/lib/cline/sessions.rb

@@ -0,0 +1,30 @@
+module Cline
+  # Provide a set of sessions from a directory
+  class Sessions
+    # @!group Public API
+
+    include Utils::EnumerableDirObjects
+
+    # @!group Internal
+
+    # Constructor
+    #
+    # @param cline_models [Models] The Cline models used to interpret the sessions' 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), Session.open(dir, cline_models: @cline_models, create:)]
+    end
+  end
+end

data/lib/cline/skill.rb

@@ -0,0 +1,148 @@
+require 'front_matter_parser'
+require 'json'
+require 'yaml'
+
+module Cline
+  # A skill defined in a directory
+  class Skill
+    # @!group Public API
+
+    include Serializable::Dir
+
+    # Get the skill's name
+    #
+    # @return [String] Skill name
+    def name
+      File.basename(dir)
+    end
+
+    # Get the skill's YAML front matter
+    #
+    # @return [Hash{Symbol => Object}, nil] The skill's front matter, or nil if none
+    def yaml_front_matter
+      content = skill_file_content('SKILL.md')&.content
+      JSON.parse(JSON[FrontMatterParser::Parser.new(:md).call(content).front_matter], symbolize_names: true) if content
+    end
+
+    # Equality check
+    #
+    # @param other [Object] The other to check equality with
+    # @return [Boolean] True if objects are equal
+    def ==(other)
+      other.is_a?(Skill) &&
+        other.name == name &&
+        other.files.compact == files.compact
+    end
+
+    # Get the files of this skill
+    #
+    # @return [Hash{String => FileContent, nil}] The files
+    def files
+      discover_files
+      @files
+    end
+
+    # Save the skill files
+    def save
+      raise 'This instance has not been initialized from a Skill directory' unless dir
+
+      # First create/update all known files
+      files.each do |file_path, file_content|
+        next unless file_content
+
+        file_full_path = File.join(dir, file_path)
+        FileUtils.mkdir_p(File.dirname(file_full_path))
+        File.write(file_full_path, file_content.content)
+      end
+      # Then delete any file that is not known
+      each_file do |file_path|
+        File.unlink(File.join(dir, file_path)) unless files[file_path]
+      end
+    end
+
+    # @return [Boolean] Is the skill enabled?
+    def enabled?
+      !yaml_front_matter || yaml_front_matter[:disabled] != true
+    end
+
+    # Enable the skill
+    def enable
+      return if enabled?
+
+      modify_skill_front_matter do |front_matter|
+        front_matter.except('disabled')
+      end
+    end
+
+    # Disable the skill
+    def disable
+      return unless enabled?
+
+      modify_skill_front_matter do |front_matter|
+        front_matter.merge('disabled' => true)
+      end
+    end
+
+    # @!group Internal
+
+    # Constructor
+    def initialize
+      @files = {}
+      @files_discovered = false
+    end
+
+    private
+
+    # Loop over all existing relative file paths inside our directory
+    #
+    # @yield The code to execute for each file found
+    # @yieldparam file_path [String] The relative file path
+    def each_file
+      dir_regexp = %r{^#{Regexp.escape(dir)}/}
+      Dir.glob("#{dir}/**/*", File::FNM_DOTMATCH).each do |path|
+        yield(path.gsub(dir_regexp, '')) unless File.directory?(path)
+      end
+    end
+
+    # Discover all files of this skill.
+    # Remember when files were discovered to cache it.
+    def discover_files
+      return if @files_discovered
+
+      each_file do |file_path|
+        skill_file_content(file_path)
+      end
+      @files_discovered = true
+    end
+
+    # Get the file content from a file path in this skill
+    #
+    # @param file_path [String] The file path to retrieve content from
+    # @return [FileContent, nil] The file content, or nil if none
+    def skill_file_content(file_path)
+      @files[file_path] = FileContent.open(subpath(file_path)) unless @files.key?(file_path)
+      @files[file_path]
+    end
+
+    # Modify the content of a skill file's front matter
+    #
+    # @yield [front_matter] The block to execute to modify the front matter
+    # @yieldparam front_matter [Hash] The parsed front matter hash
+    # @yieldreturn [Hash] The modified front matter hash
+    def modify_skill_front_matter
+      content = skill_file_content('SKILL.md')&.content
+      unless content
+        # Initialize it
+        files['SKILL.md'] = FileContent.new("---\n\n\n---\n")
+        content = skill_file_content('SKILL.md').content
+      end
+      new_front_matter = yield(YAML.safe_load(content.match(/^---\n(.+?)\n---/m)[1]) || {})
+      content.replace(
+        content.gsub(
+          /^---\n(.+?)\n---/m,
+          "---\n#{YAML.dump(new_front_matter).gsub(/\A---\n/, '') unless new_front_matter.empty?}---"
+        )
+      )
+    end
+  end
+end

data/lib/cline/skills.rb

@@ -0,0 +1,8 @@
+module Cline
+  # Provide a set of skills from a directory
+  class Skills
+    # @!group Public API
+
+    Utils::EnumerableDirObjects.include_for(self, Skill)
+  end
+end