x_aeon_agents 1.0.28

data/lib/x_aeon_agents/gen_helpers.rb

@@ -0,0 +1,270 @@
+require 'erb'
+require 'yaml'
+
+module XAeonAgents
+  # Helper methods for generating skill content
+  module GenHelpers
+    # @!group Public API
+
+    # Define a skill metadata.
+    # This should always be the first call in a skill ERB file.
+    # It also returns the corresponding YAML frontmatter.
+    # The name is automatically derived from skill_name.
+    #
+    # @param description [String] Description of the skill
+    # @param dependencies [Array<String>] List of skills dependencies
+    # @param plan [Boolean] Is this skill applicable to plan mode?
+    # @param metadata [Hash] Optional metadata key-value pairs
+    # @return [String] The complete YAML frontmatter block (including --- delimiters)
+    def skill(description:, dependencies: [], plan: false, metadata: {})
+      @plan = plan
+      frontmatter = {
+        'name' => name,
+        'description' => "#{description}#{' Use this skill also in Plan mode.' if plan}"
+      }
+      metadata['agent'] = 'Plan' if plan
+      metadata['dependencies'] = dependencies unless dependencies.empty?
+      frontmatter['metadata'] = metadata.transform_keys(&:to_s) unless metadata.empty?
+      "#{YAML.dump(frontmatter, line_width: -1).chomp}\n---"
+    end
+
+    # Define or get the skill goal to be used in ERB templates
+    #
+    # @param goal_desc [String, nil] The skill goal, or nil to retrieve the previously set skill goal
+    # @return [String] The skill goal
+    def goal(goal_desc = nil)
+      @skill_goal = goal_desc unless goal_desc.nil?
+      @skill_goal
+    end
+
+    # Get the skill goal as a sentence
+    # Prerequisite: skill_goal should be set before.
+    #
+    # @return [String] The skill goal as useable inside a sentence
+    def goal_sentence
+      "#{@skill_goal[0].downcase}#{@skill_goal[1..]}"
+    end
+
+    # Return the prompt to announce that the agent is working on a skill.
+    # Prerequisite: skill_goal should be set before.
+    def announce
+      "Always tell the user \"SKILL: I am #{goal_sentence}\" to inform the user that you are running this skill."
+    end
+
+    # Return a default temporary folder that agents can use in a project.
+    # It's better to force it to the agents, as some models will try weird CLI commands to create temporary files otherwise.
+    #
+    # @return [String] Temporary folder path
+    def tmp_path
+      "#{Config.data_dir}/tmp"
+    end
+
+    # Generate a rule documentation block with examples and rationale.
+    #
+    # @param title [String] The rule title
+    # @param description [String, nil] The additional description
+    # @param type [Symbol] The code block language type (e.g., :bash, :ruby)
+    # @param bad [String, nil] The incorrect example
+    # @param good [String, nil] The correct example
+    # @param rationale [String, nil] The explanation for why this rule exists
+    # @return [String] The formatted markdown documentation for the rule
+    def rule(title, description: nil, type: :ruby, bad: nil, good: nil, rationale: nil)
+      markdown_sections = [
+        <<~EO_MARKDOWN
+          ### Rule: #{title}#{"\n\n#{description.strip}" unless description.nil?}
+        EO_MARKDOWN
+      ]
+      unless bad.nil?
+        markdown_sections << <<~EO_MARKDOWN
+          #### Example: Incorrect
+
+          ```#{type}
+          #{bad.strip}
+          ```
+        EO_MARKDOWN
+      end
+      unless good.nil?
+        markdown_sections << <<~EO_MARKDOWN
+          #### Example: Correct
+
+          ```#{type}
+          #{good.strip}
+          ```
+        EO_MARKDOWN
+      end
+      unless rationale.nil?
+        markdown_sections << <<~EO_MARKDOWN
+          #### Rationale
+
+          #{rationale}
+        EO_MARKDOWN
+      end
+      markdown_sections.join("\n").strip
+    end
+
+    # Define an ordered todo list for a skill.
+    # Captures the ERB block content, parses its ## sections, numbers them starting at 2
+    # (section 1 "Inform the USER" is auto-generated), and wraps everything with the
+    # standard skill header, checklist initialization, and final verification sections.
+    #
+    # @param erb_block [#call] ERB block containing the markdown sections
+    # @return [String] The formatted todo list
+    def ordered_todo_list(&erb_block)
+      transform_erb_block(erb_block) do |erb_content|
+        # Split into sections by ## headings
+        # Number sections starting from 2 and strip trailing whitespace
+        step_number = 2
+        numbered_sections = erb_content
+          .strip
+          .split(/^(?=### )/)
+          .reject { |s| s.strip.empty? }
+          .map do |section|
+            numbered = section.sub(/^### /, "### #{step_number}. ").rstrip
+            step_number += 1
+            numbered
+          end
+
+        # Compose the full output and append directly to ERB buffer
+        # (we use <% %> not <%= %> since standard ERB doesn't support <%= method do %>)
+        <<~EO_MARKDOWN
+          ## Sequential steps to be followed when using this skill
+
+          When #{goal_sentence}, follow those steps.
+
+          #{init_skill_checklist(name).rstrip}
+
+          ### 1. Inform the user
+
+          - #{announce}
+
+          #{numbered_sections.join("\n\n")}
+
+          #{validate_skill_checklist(name).rstrip}
+        EO_MARKDOWN
+      end
+    end
+
+    # Return the skill config hash from its .skill_config.yml file, if it exists.
+    #
+    # @param skill_name [String] The skill name (matching a directory under skills.src/)
+    # @return [Hash] The YAML config hash, or an empty Hash if no config file exists
+    def self.config(skill_name)
+      skill_config_file = "skills.src/#{skill_name}/.skill_config.yml"
+      File.exist?(skill_config_file) ? YAML.load_file(skill_config_file) : {}
+    end
+
+    # Return the skill being generated
+    #
+    # @return [String] Skill name being generated
+    def name
+      current_erb_file.match(%r{/skills\.src/([^/]+)/})[1]
+    end
+
+    # Generate the "When to use it" section for a skill.
+    # This helper automatically includes standard items and custom usage instructions.
+    #
+    # @param erb_block [#call] ERB block containing custom usage instructions
+    # @return [String] The formatted "When to use it" section
+    def when_to_use(&erb_block)
+      transform_erb_block(erb_block) do |erb_content|
+        blocks = []
+        blocks << '- This skill can be used when in Plan mode.' if @plan
+        blocks << "- Always use it every time another skill specifically mentions `skill: #{name}`."
+        blocks << erb_content
+        <<~EO_MARKDOWN
+          ## When to use it
+
+          #{blocks.join("\n").rstrip}
+        EO_MARKDOWN
+      end
+    end
+
+    # Small class that can serve as a container for ERB evaluation with our DSL
+    class ErbEvaluator
+      include GenHelpers
+
+      # Constructor
+      #
+      # @param erb_file [String] File containing the ERB template
+      def initialize(erb_file)
+        @erb = ERB.new(File.read(erb_file), trim_mode: '-')
+        # Use filename for better error reporting
+        @erb.filename = erb_file
+      end
+
+      # Evaluate the ERB template
+      #
+      # @return [String] The evaluated ERB result
+      def result
+        @erb.result(binding)
+      end
+    end
+
+    private
+
+    # Return the execution checklist initialization section
+    #
+    # @param checklist_name [String] Name to be given to this checklist
+    # @return [String] The execution checklist section
+    def init_skill_checklist(checklist_name)
+      <<~EO_MARKDOWN
+        ### Create the #{checklist_name} Execution Checklist (MANDATORY)
+
+        - Before executing anything, create a checklist named #{checklist_name} Execution Checklist with all steps of these instructions.
+        - The #{checklist_name} Execution Checklist must include all numbered steps explicitly.
+        - After completing each step of these instructions, mark the item in the #{checklist_name} Execution Checklist as completed.
+        - Do not skip any item.
+        - If an item cannot be executed, explicitly explain why.
+        - Never mark the task as completed while any item from the #{checklist_name} Execution Checklist remains open.
+      EO_MARKDOWN
+    end
+
+    # Return the final verification section
+    #
+    # @param checklist_name [String] Name to be given to this checklist
+    # @return [String] The final verification section
+    def validate_skill_checklist(checklist_name)
+      <<~EO_MARKDOWN
+        ### Final Verification (MANDATORY)
+
+        Before declaring the task complete:
+
+        - Re-list all numbered steps from the #{checklist_name} Execution Checklist.
+        - Confirm each one was executed.
+        - If any step was not executed, execute it now.
+      EO_MARKDOWN
+    end
+
+    # Return the ERB file being generated
+    #
+    # @return [String] ERB file being generated
+    def current_erb_file
+      file_found = caller.find { |stack_trace| stack_trace =~ %r{(/skills\.src/.+\.erb)} }
+      raise "Unable to find ERB file among stack:\n#{caller.join("\n")}" if file_found.nil?
+
+      Regexp.last_match[1]
+    end
+
+    # Capture the ERB content inside a code block, and return a user-transformed version of it.
+    # Handle indentation properly by removing the indentation caused by the ERB call itself.
+    #
+    # @param erb_block [#call] The block containing ERB content
+    # @yield [#call(erb_content) -> String] The code that should transform the content
+    # @yieldparam erb_content [String] The ERB content
+    # @yieldreturn [String] The transformed content
+    def transform_erb_block(erb_block)
+      # Capture the ERB block content using buffer manipulation
+      erb_buffer = eval('_erbout', erb_block.binding, __FILE__, __LINE__)
+      saved_content = erb_buffer.dup
+      erb_buffer.clear
+      erb_block.call
+      captured = erb_buffer.dup
+      erb_buffer.replace(saved_content)
+
+      # Dedent the captured content: remove common leading whitespace
+      lines = captured.lines
+      min_indent = lines.reject { |l| l.strip.empty? }.map { |l| l.match(/^(\s*)/)[1].length }.min || 0
+      erb_buffer << yield(lines.map { |l| l.strip.empty? ? "\n" : l[min_indent..] }.join)
+    end
+  end
+end

data/lib/x_aeon_agents/helpers.rb

@@ -0,0 +1,211 @@
+require 'fileutils'
+require 'git'
+require 'launchy'
+require 'octokit'
+require 'open3'
+require 'secret_string'
+
+module XAeonAgents
+  # Various helpers and utilities that are used internally
+  module Helpers
+    # Exception class used to identify commands not returning the expected exit status
+    class UnexpectedExitStatusError < StandardError
+    end
+
+    class << self
+      include Logger
+
+      # Retrieve API keys needed for the agents from the X-Aeon launcher
+      #
+      # @return [Hash{Symbol => SecretString}] The keys retrieved
+      def keys_from_launcher
+        @keys_from_launcher ||= begin
+          keys = {
+            cline_api_key: 'Cline API key',
+            github_token: 'Github API token',
+            openrouter_api_key: 'OpenRouter API key'
+          }
+          launcher_keys = {}
+          Bundler.with_unbundled_env { `launcher safe -- #{keys.values.map { |launcher_key| "\"#{launcher_key}\"" }.join(' ')}` }.each_line do |line|
+            next unless line =~ /^\[PASSWORD\] \[([^\]]+)\]: (.+)$/
+
+            launcher_keys[Regexp.last_match(1)] = SecretString.new(Regexp.last_match(2))
+          end
+          keys.to_h { |key, launcher_key| [key, launcher_keys[launcher_key]] }
+        end
+      end
+
+      # Execute a command while capturing its output in real time
+      #
+      # @param cmd [String] Command to be run
+      # @param expected_exit_status [Integer, nil] Expected exit status, or nil for no expectation
+      # @return [Hash{Symbol => Object}] Command final output
+      #   - stdout [String] Full stdout
+      #   - stderr [String] Full stderr
+      #   - exit_status [Integer] Exit status
+      def run_cmd(cmd, expected_exit_status: 0)
+        stdout_lines = []
+        stderr_lines = []
+        exit_status = nil
+        Open3.popen3(cmd) do |stdin, stdout, stderr, wait_thr|
+          stdin.close
+          [
+            # Parse stdout
+            Thread.new do
+              stdout.each_line do |line|
+                stdout_lines << line
+              end
+            end,
+            # Parse stderr
+            Thread.new do
+              stderr.each_line do |line|
+                stderr_lines << line
+              end
+            end
+          ].each(&:join)
+          exit_status = wait_thr.value.exitstatus
+          log_debug "Command `#{cmd}` exited with status: #{exit_status}"
+          if !expected_exit_status.nil? && exit_status != expected_exit_status
+            raise UnexpectedExitStatusError, "Command `#{cmd}` exited with status #{exit_status} (expected #{expected_exit_status})"
+          end
+        end
+        {
+          stdout: stdout_lines.join,
+          stderr: stderr_lines.join,
+          exit_status:
+        }
+      end
+
+      # Get a Git instance on the current directory.
+      # Keep a cache of it.
+      #
+      # @return [Git::Base] The git instance
+      def git
+        @git ||= Git.open(Dir.pwd)
+      end
+
+      # Return a list of patch description of diffs in the git staging area.
+      #
+      # @return [String] Patches in the staging area
+      def git_diff_cached
+        # TODO: Use ruby-git when the --cached feature will be implemented
+        `git diff --cached`.strip
+      end
+
+      # Get a current files diffs
+      #
+      # @param base [String, Symbol] Git base (sha, objectish...) with which we diff, or :cached to only get diff of the staging area.
+      def artifact_files_diffs(base = 'HEAD')
+        if base == :cached
+          <<~EO_ARTIFACT
+            ### git diff --cached
+
+            ```
+            #{git_diff_cached}
+            ```
+          EO_ARTIFACT
+        else
+          <<~EO_ARTIFACT
+            ### New untracked files
+
+            #{git.status.untracked.keys.map do |file|
+              <<~EO_UNTRACKED_FILE
+                #### #{file}
+                ```
+                #{File.read(file)}
+                ```
+              EO_UNTRACKED_FILE
+            end.join("\n")}
+
+            ### git diff
+
+            ```
+            #{git.diff(base)}
+            ```
+          EO_ARTIFACT
+        end
+      end
+
+      # Get a Github Octokit API instance.
+      # Keep a cache of it.
+      #
+      # @return [Octokit::Client] The Octokit client
+      def github
+        @github ||= Octokit::Client.new(access_token: Config.github_token)
+      end
+
+      # Get the Github remote from the Git remotes.
+      # Keep a cache of it.
+      #
+      # @return [Git::Remote, nil] The Github remote instance, or nil if none
+      def github_remote
+        @github_remote ||= git.remotes.find { |remote| remote.url.match(%r{github\.com[:/].+\.git}) }
+      end
+
+      # Get the current repository name from the Git remote URL.
+      # Keep a cache of it.
+      #
+      # @return [String, nil] The Github repository name in the format "owner/repo", or nil if none
+      def github_repo
+        @github_repo ||= github_remote && github_remote.url.match(%r{github\.com[:/](.+)\.git})[1]
+      end
+
+      # Get the Ruby gem name from the gemspec file, if any.
+      # Returns nil if no gemspec exists.
+      #
+      # @return [String, nil] The gem name, or nil
+      def gem_name
+        @gem_name ||= begin
+          gemspec_files = Dir['*.gemspec']
+          Gem::Specification.load(gemspec_files.first).name unless gemspec_files.empty?
+        end
+      end
+
+      # Allow user to review and edit content before using it
+      #
+      # @param reviews_dir [String] Directory that can be used to store files to be reviewed
+      # @param name [String] Name used for the temporary file
+      # @param description [String] Description shown to the user
+      # @param editable [Boolean] Indicates if user can edit the content
+      # @param promptable [Boolean] Indicates if user can issue a prompt as an answer
+      # @param content [String] Initial content to present
+      # @return [Array<String>] 2 values are returned:
+      #   - [String] Content after user review (same as content if editable is false)
+      #   - [String] User prompt
+      def review_content(
+        reviews_dir: "#{Config.data_dir}/reviews",
+        name: 'content.txt',
+        description: 'Content to be reviewed',
+        editable: true,
+        promptable: false,
+        content: ''
+      )
+        content_file = "#{reviews_dir}/#{Time.now.utc.strftime('%F-%H-%M-%S')}-#{name}"
+        FileUtils.mkdir_p File.dirname(content_file)
+        File.write(content_file, content)
+        begin
+          Launchy.open(content_file)
+          puts
+          puts <<~EO_STDOUT
+            Review the following content: #{description}.
+            #{
+              (
+                (editable ? ['Modify the file and save it to take your changes into consideration'] : []) + [
+                  'Hit Enter to continue',
+                  'Hit Ctrl-C to cancel and interrupt'
+                ] + (promptable ? ['Any other input will be used to prompt again the generation of this content'] : [])
+              ).map { |option| "* #{option}" }.join("\n")
+            }
+          EO_STDOUT
+          user_prompt = $stdin.gets
+          [
+            editable ? File.read(content_file).strip : content,
+            user_prompt.strip
+          ]
+        ensure
+          FileUtils.rm_f content_file unless Config.debug
+        end
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/logger.rb

@@ -0,0 +1,21 @@
+module XAeonAgents
+  # Mixin adding logging capabilities
+  module Logger
+    class << self
+      # Global debug switch.
+      attr_accessor :debug
+    end
+
+    # Log a message if debug was activated
+    #
+    # @param msg [String, nil] Message to be displayed, or nil if the message is given lazily through a code block
+    # @yield [#call -> String] Optional code returning a [String] for lazy evaluation
+    # @yieldreturn [String] The message to be displayed
+    def log_debug(msg = nil)
+      return unless Logger.debug
+
+      msg = yield if block_given?
+      puts "[DEBUG] - #{msg}"
+    end
+  end
+end

data/lib/x_aeon_agents/providers/cline.rb

@@ -0,0 +1,78 @@
+require 'ruby_llm/message'
+require 'ruby_llm/thinking'
+require 'ruby_llm/providers/openai'
+require 'ruby_llm/providers/openrouter/chat'
+require 'ruby_llm/providers/openrouter/models'
+require 'ruby_llm/providers/openrouter/streaming'
+require 'ruby_llm/providers/openrouter/images'
+
+module XAeonAgents
+  # Collection of providers for ai-agents
+  module Providers
+    # Cline API integration.
+    class Cline < RubyLLM::Providers::OpenAI
+      # @return [String] The base API URL
+      def api_base
+        @config.cline_api_base || 'https://api.cline.bot/api/v1'
+      end
+
+      # @return [Hash{String => String}] HTTP headers to add to the queries
+      def headers
+        {
+          'Authorization' => "Bearer #{@config.cline_api_key}"
+        }
+      end
+
+      # Parses the completion response from the Cline API into a [RubyLLM::Message].
+      #
+      # Handles empty responses, API errors, message extraction, content/thinking parsing,
+      # token usage tracking (including cached and reasoning tokens), and tool calls.
+      #
+      # @param response [Faraday::Response] The raw HTTP response from the Cline API.
+      # @return [RubyLLM::Message, nil] The parsed message, or nil if the response body is empty
+      #   or no message data is present.
+      def parse_completion_response(response)
+        data = response.body
+        return if data.empty?
+
+        raise Error.new(response, data['error']) if data['error']
+
+        message_data = data.dig('data', 'choices', 0, 'message')
+        return unless message_data
+
+        usage = data.dig('data', 'usage') || {}
+        cached_tokens = usage.dig('prompt_tokens_details', 'cached_tokens')
+        thinking_tokens = usage.dig('completion_tokens_details', 'reasoning_tokens')
+        content, thinking_from_blocks = extract_content_and_thinking(message_data['content'])
+        thinking_text = thinking_from_blocks || extract_thinking_text(message_data)
+        thinking_signature = extract_thinking_signature(message_data)
+
+        RubyLLM::Message.new(
+          role: :assistant,
+          content: content,
+          thinking: RubyLLM::Thinking.build(text: thinking_text, signature: thinking_signature),
+          tool_calls: parse_tool_calls(message_data['tool_calls']),
+          input_tokens: usage['prompt_tokens'],
+          output_tokens: usage['completion_tokens'],
+          cached_tokens: cached_tokens,
+          cache_creation_tokens: 0,
+          thinking_tokens: thinking_tokens,
+          model_id: data.dig('data', 'model'),
+          raw: response
+        )
+      end
+
+      class << self
+        # @return [Array<Symbol>] The required configuration keys for the Cline provider.
+        def configuration_requirements
+          %i[cline_api_base cline_api_key]
+        end
+
+        # @return [Array<Symbol>] The available configuration keys for the Cline provider.
+        def configuration_options
+          %i[cline_api_base cline_api_key]
+        end
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/version.rb

@@ -0,0 +1,6 @@
+module XAeonAgents
+  # @!group Global API
+
+  # Gem version
+  VERSION = '1.0.28'
+end

data/lib/x_aeon_agents.rb

@@ -0,0 +1,38 @@
+require 'zeitwerk'
+
+Zeitwerk::Loader.for_gem.setup
+
+# As most agents come from composable_agents, require it here just once.
+require 'composable_agents'
+
+# Provide skills, tools, agents and workflows that allow AI to be used in X-Aeon projects.
+module XAeonAgents
+  # Return the current AI agent name
+  #
+  # @return [String] The current AI agent name
+  def self.agent_name
+    # TODO: Make this adaptable to different agents using plugins
+    require 'sqlite3'
+    require 'json'
+
+    # Find VSCode globalStorage database
+    state_db = "#{ENV['VSCODE_PORTABLE'] ? "#{ENV['VSCODE_PORTABLE']}/user-data" : "#{ENV.fetch('APPDATA', nil)}/Code"}/User/globalStorage/state.vscdb"
+    raise "Cannot find #{state_db}" unless File.exist?(state_db)
+
+    # Open SQLite database and query for our extension's key
+    db = SQLite3::Database.new(state_db)
+    db.results_as_hash = true
+    row = db.get_first_row('SELECT value FROM ItemTable WHERE key = ?', 'saoudrizwan.claude-dev')
+    db.close
+    raise 'Key \'saoudrizwan.claude-dev\' not found in database.' unless row
+
+    "Cline (#{JSON.parse(row['value'])['actModeOpenRouterModelId']})"
+  end
+
+  # Return the agent signature that is added in any description authored by the AI agent
+  #
+  # @return [String] AI agent signature
+  def self.agent_signature
+    "\n\nCo-authored by: #{agent_name}"
+  end
+end