x_aeon_agents 1.0.28

data/lib/x_aeon_agents/agent_defaults.rb

@@ -0,0 +1,60 @@
+module XAeonAgents
+  # Mixin setting up default settings for agents.
+  # This mixin is meant to be the last prepended mixin in all Agent classes.
+  module AgentDefaults
+    class << self
+      # Get the singleton session ID.
+      # If it is the first time it is invoked, use a default session ID.
+      def singleton_session_id
+        @singleton_session_id ||= Time.now.utc.strftime('%Y-%m-%d-%H-%M-%S-%N')
+      end
+    end
+
+    # Instantiate a new agent.
+    # Transfer the same session to the new agent.
+    #
+    # @param agent_class [Class] The agent class to be instantiated
+    # @param args [Array] Constructor parameters
+    # @param kwargs [Hash] Constructor kwargs
+    # @return [ComposableAgents::Agent] The new agent
+    def new_agent(agent_class, *args, **kwargs)
+      agent_class.new(*args, session_id: @session_id, **kwargs)
+    end
+
+    # Hook called when this mixin is prepended in a class
+    #
+    # @param base [Class] The base class prepending this mixin
+    def self.prepended(base)
+      base.prepend ComposableAgents::Mixins::ArtifactContract unless base.ancestors.include?(ComposableAgents::Mixins::ArtifactContract)
+      base.prepend ComposableAgents::Mixins::Resumable unless base.ancestors.include?(ComposableAgents::Mixins::Resumable)
+      # Make sure we always prepend at the top our initializer that sets all defaults
+      base.prepend(
+        Module.new do
+          # Constructor
+          #
+          # @param args [Array] Agent's constructor arguments
+          # @param session_id [String, nil] Specific X-Aeon session id to be used, or nil if none
+          # @param kwargs [Array] Agent's constructor kwargs
+          def initialize(*args, session_id: nil, **kwargs)
+            # If we inherit from some frameworks initialize them now.
+            Config.setup_composable_agents
+            case self
+            when ComposableAgents::AiAgents::Agent
+              Config.setup_ai_agents
+            when ComposableAgents::Cline::Agent
+              Config.setup_cline
+            end
+            @session_id = session_id || AgentDefaults.singleton_session_id
+            @session_dir = "#{Config.data_dir}/sessions/#{@session_id}"
+            super(
+              *args,
+              composable_agents_dir: "#{@session_dir}/composable_agents",
+              run_id: "#{@session_id}-#{kwargs[:name] || self.class.name.split('::').last}",
+              **kwargs
+            )
+          end
+        end
+      )
+    end
+  end
+end

data/lib/x_aeon_agents/agent_options.rb

@@ -0,0 +1,58 @@
+module XAeonAgents
+  # Provide agent options for different agent categories
+  class AgentOptions
+    # @!group Public API
+
+    # Get an agent's option for a given agent category.
+    # Those options can be given directly to the agent's constructor to tune it for the desired category.
+    #
+    # @param agent_category [String] The agent category for which we want the agent's options
+    # @return [Hash{Symbol => Object}, nil] The corresponding agent's options, or nil if none
+    def [](agent_category)
+      # Lazy-evaluate it if needed
+      options[agent_category] = options[agent_category].call if options[agent_category].is_a?(Proc)
+      options[agent_category]
+    end
+
+    # Set an agent's option for a given agent category.
+    #
+    # @param agent_category [String] The agent category for which we want the agent's options
+    # @param agent_options [Hash{Symbol => Object}, #call -> Hash] The corresponding agent's options (can be lazily evaluated)
+    def []=(agent_category, agent_options)
+      options[agent_category] = agent_options
+    end
+
+    private
+
+    # @return [Hash{String => Hash{Symbol => Object}, #call -> Hash}] The memoized options (can be lazily evaluated), per agent category.
+    def options
+      @options ||= {
+        'free_simple' => {
+          model: 'openrouter/free',
+          strategy: ComposableAgents::PromptRenderingStrategy::Markdown
+        },
+        'free_complex' => proc do
+          {
+            model: 'tencent/hy3:free',
+            api_key: Config.cline_api_key,
+            cli_options: Config.default_cline_cli_args
+          }
+        end,
+        'free_complex_planning' => proc do
+          {
+            model: 'tencent/hy3:free',
+            api_key: Config.cline_api_key,
+            cli_options: Config.default_cline_cli_args.merge(
+              {
+                plan: true
+              }
+            ),
+            configure_global: proc do |global_settings|
+              global_settings.disabled_tools = %w[editor run_commands]
+            end
+          }
+        end
+      }
+    end
+  end
+end

data/lib/x_aeon_agents/agents/coder_agent.rb

@@ -0,0 +1,82 @@
+module XAeonAgents
+  # Collection of agents that can be used
+  module Agents
+    # Agent responsible for implementing tasks following an implementation plan
+    class CoderAgent < ComposableAgents::Cline::Agent
+      prepend AgentDefaults
+
+      # Define input artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
+      def input_artifacts_contracts
+        super.merge(plan: 'The implementation plan that you must follow')
+      end
+
+      # Constructor
+      #
+      # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+      def initialize(**agent_params)
+        super(
+          name: 'Coder',
+          role: 'You are a Coder agent',
+          objective: <<~EO_OBJECTIVE,
+            Your primary goal is to assist users with various coding tasks by leveraging your knowledge and the tools at your disposal.
+            Given the user's prompt, you should use the tools available to you to answer user's question.
+          EO_OBJECTIVE
+          system_instructions: <<~EO_INSTRUCTIONS,
+            Always gather all the necessary context before starting to work on a task.
+            For example, if you are generating a unit test or new code, make sure you understand the requirement, the naming conventions, frameworks and libraries used and aligned in the current codebase, and the environment and commands used to run and test the code etc.
+            Always validate the new unit test at the end including running the code if possible for live feedback.
+
+            Begin by analyzing the user's input and gathering any necessary additional context.
+            Then, present your plan at the start of your response along with tool calls before proceeding with the task.
+            It's OK for this section to be quite long.
+
+            Review each question carefully and answer it with detailed, accurate information.
+
+            If you need more information, use one of the available tools or ask for clarification instead of making assumptions or lies.
+
+            When you have completed the task, please provide a summary of what you did and any relevant information that the user should know.
+            This will help ensure that the user understands the changes made and can easily follow up if they have any questions or need further assistance.
+          EO_INSTRUCTIONS
+          constraints: <<~EO_CONSTRAINTS,
+            Remember:
+            - Always adhere to existing code conventions and patterns.
+            - Use only libraries and frameworks that are confirmed to be in use in the current codebase.
+            - Provide complete and functional code without omissions or placeholders.
+            - Be explicit about any assumptions or limitations in your solution.
+            - Always show your planning process before executing any task.
+              This will help ensure that you have a clear understanding of the requirements and that your approach aligns with the user's needs.
+            - Always use absolute paths when referring to files.
+            - You can call multiple tools in a single response.
+              Before using tools, identify every independent read, search, command, or edit needed for the next step and emit all of those tool calls now, either as multiple tool calls or as one batched input for tools that accept arrays.
+              Do not wait for one independent result before requesting another.
+              Do not split independent reads, searches, checks, or edits across separate turns.
+            - Good parallelism examples: read all known relevant files in one read_files call;
+              run independent inspection commands in one run_commands call;
+              emit independent read_files, search_codebase, and run_commands calls together in one response;
+              emit multiple editor calls together when editing different files or non-overlapping regions.
+            - Always verify the files you have edited or created at the end of the task to ensure they are completed and working as expected.
+
+            REMEMBER, be helpful and proactive!
+            Don't ask for permission to do something when you can do it!
+            Do not indicates you will be using a tool unless you are actually going to use it.
+
+            IMPORTANT: Always includes tool calls in your response until the task is completed.
+            Response without tool calls will be considered as completed with the final answer.
+
+            Do not indicate that you will perform an action without actually doing it.
+            Always provide the final result in your response.
+            Always validate your answer with checking the code and running it if possible.
+          EO_CONSTRAINTS
+          skills: %w[
+            applying-ruby-conventions
+            applying-test-conventions
+            enforcing-project-rules
+          ],
+          **agent_params
+        )
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/agents/committer_agent.rb

@@ -0,0 +1,71 @@
+module XAeonAgents
+  module Agents
+    # Agent responsible for git committing locally staged or modified files
+    class CommitterAgent < ComposableAgents::Agent
+      prepend AgentDefaults
+
+      # Constructor
+      #
+      # @param user_review [Boolean] Should the agent ask for user's git comment review?
+      # @param stage [Symbol] Apply different staging strategies:
+      #   - `all`: Always stage all files
+      #   - `if_empty`: Stage all files only if the staging aread is empty
+      #   - `none`: Don't stage anything
+      # @param authors [Array<Agent>] List of agents that should be credited as authors of this commit
+      # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+      def initialize(user_review: true, stage: :if_empty, authors: [], **agent_params)
+        super(name: 'Committer', **agent_params)
+        @user_review = user_review
+        @stage = stage
+        @authors = authors
+      end
+
+      # Execute the agent to generate some output artifacts based on some input artifacts.
+      #
+      # @return [Hash{Symbol => Object}] Output artifacts content
+      def run
+        case @stage
+        when :all
+          Helpers.git.add(all: true)
+        when :if_empty
+          Helpers.git.add(all: true) if Helpers.git_diff_cached.empty?
+        when :none
+          # Do nothing
+        else
+          raise "Unknown staging strategy: #{@stage}"
+        end
+        if Helpers.git_diff_cached.empty?
+          log_debug 'Nothing to commit'
+        else
+          git_diff_interpreter_agent = GitDiffInterpreterAgent.new
+          git_diff_interpreter_agent_output = git_diff_interpreter_agent.run(git_ref_base: 'cached')
+          content = <<~EO_COMMIT
+            #{git_diff_interpreter_agent_output[:one_line_summary].strip}
+
+            #{git_diff_interpreter_agent_output[:change_intent].strip}
+
+            Co-authored by X-Aeon AI Agents:
+            #{
+              (@authors + [git_diff_interpreter_agent.diff_interpreter_agent]).map do |agent|
+                "* #{agent.full_name}"
+              end.join("\n")
+            }
+          EO_COMMIT
+          if @user_review
+            content, _user_prompt = Helpers.review_content(
+              name: 'commit.md',
+              description: 'Git commit comment',
+              editable: true,
+              content:
+            )
+          end
+          Helpers.git.commit(content)
+
+          puts
+          puts 'Commit created successfully.'
+        end
+        {}
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/agents/developer_agent.rb

@@ -0,0 +1,235 @@
+require 'diffy'
+
+module XAeonAgents
+  module Agents
+    # Agent responsible for developing some requirements
+    class DeveloperAgent < ComposableAgents::Agent
+      prepend AgentDefaults
+
+      # Define input artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
+      def input_artifacts_contracts
+        { requirements: 'The initial requirements that need to be implemented' }
+      end
+
+      # Constructor
+      #
+      # @param commit [Boolean] Should we commit files at every step?
+      # @param pull_request [Boolean] Should we create a Github Pull Request with this implementation?
+      # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+      def initialize(commit: false, pull_request: false, **agent_params)
+        super(name: 'Developer', **agent_params)
+        @commit = commit
+        @pull_request = pull_request
+      end
+
+      # Execute the agent to generate some output artifacts based on some input artifacts.
+      #
+      # @param requirements [String] Requirements to be implemented
+      # @return [Hash{Symbol => Object}] Output artifacts content
+      def run(requirements:)
+        # Initial artifacts
+        step(:setup_requirements) do
+          @artifacts.merge!(
+            requirements:,
+            base_sha: Helpers.git.gcommit('HEAD').sha
+          )
+        end
+
+        planner_agent = new_agent(PlannerAgent)
+        step_agent(planner_agent)
+
+        coder_agent = new_agent(CoderAgent, **Config.agent_options['free_complex'])
+
+        step_agent(
+          coder_agent,
+          user_instructions: "Follow all the steps of the implementation plan described in the artifact named `#{coder_agent.artifact_ref(:plan)}`."
+        )
+        puts "===== Coder changes: #{Helpers.git.status.changed.keys.join(', ')}"
+
+        step_agent(new_agent(CommitterAgent, user_review: false, stage: :all, authors: [coder_agent])) if @commit
+
+        tester_agent = new_agent(TesterAgent, **Config.agent_options['free_complex'])
+
+        step(:test) do
+          tests_cmd = 'bundle exec rspec --format documentation'
+          @artifacts[:tests_cmd] = tests_cmd
+          idx_test = 0
+          loop do
+            puts
+            puts "===== Run tests ##{idx_test}..."
+            test_result = Helpers.run_cmd(tests_cmd, expected_exit_status: nil)
+            puts "Tests ##{idx_test} exit status: #{test_result[:exit_status]}"
+            @artifacts[:tests_output] = <<~EO_ARTIFACT
+              ```
+              #{test_result[:stdout]}
+              ```
+            EO_ARTIFACT
+            break if test_result[:exit_status].zero?
+
+            @artifacts[:files_diffs] = Helpers.artifact_files_diffs(@artifacts[:base_sha])
+            step_agent(
+              tester_agent,
+              user_instructions: {
+                ordered_list: [
+                  <<~EO_STEP,
+                    Understand the initial requirements from the artifact named `#{tester_agent.artifact_ref(:requirements)}`
+
+                    - Understand those requirements and their intent.
+                  EO_STEP
+                  <<~EO_STEP,
+                    Understand the implementation plan from the artifact named `#{tester_agent.artifact_ref(:plan)}`
+
+                    - Understand all the steps of the implementation plan.
+                  EO_STEP
+                  <<~EO_STEP,
+                    Understand the file changes from the artifact named `#{tester_agent.artifact_ref(:files_diffs)}`
+
+                    - Understand what was the intent of the developer implementing the requirements.
+                  EO_STEP
+                  <<~EO_STEP,
+                    Analyze the full output of unit tests run from the artifact named `#{tester_agent.artifact_ref(:tests_output)}`
+
+                    - Check every error reported in the output.
+                  EO_STEP
+                  'Fix any issue that unit tests are surfacing, while keeping the original intent of the requirements',
+                  'Remember any inconsistency and modification you need to make to the implementation plan ' \
+                    'so that your fixes are in-line with a better implementation plan',
+                  <<~EO_STEP
+                    Make sure all tests are running without issue after your fixes
+
+                    - You can run tests again using the provided tests command from the artifact named `#{tester_agent.artifact_ref(:tests_cmd)}` to test your own fixes.
+                  EO_STEP
+                ]
+              }
+            )
+            puts "===== Tester changes: #{Helpers.git.status.changed.keys.join(', ')}"
+            # Integrate potential implementation plan modifications
+            unless @artifacts[:plan_modifications].strip.empty?
+              plan_modifications = @artifacts.delete(:plan_modifications)
+              @artifacts[:plan] = <<~EO_PLAN
+                #{@artifacts[:plan].strip}
+
+                # Revision ##{idx_test} to the implementation plan
+
+                #{ComposableAgents::Utils::Markdown.align_markdown_headers(plan_modifications, level: 2)}
+
+              EO_PLAN
+            end
+            step_agent(new_agent(CommitterAgent, user_review: false, stage: :all, authors: [tester_agent])) if @commit
+            idx_test += 1
+          end
+        end
+
+        step_agent(new_agent(CommitterAgent, user_review: false, stage: :all, authors: [tester_agent])) if @commit
+
+        documenter_agent = new_agent(DocumenterAgent, **Config.agent_options['free_complex'])
+        @artifacts[:files_diffs] = Helpers.artifact_files_diffs(@artifacts[:base_sha])
+
+        step_agent(
+          documenter_agent,
+          user_instructions: {
+            ordered_list: [
+              <<~EO_STEP,
+                Analyze the initial requirements from the artifact named `#{documenter_agent.artifact_ref(:requirements)}`
+
+                - Those give you information about the requirements you should be documenting.
+              EO_STEP
+              <<~EO_STEP,
+                Analyze all the steps of the implementation plan from the artifact named `#{documenter_agent.artifact_ref(:plan)}`
+
+                - Those give you every step that should have been followed for this new development.
+              EO_STEP
+              <<~EO_STEP,
+                Analyze the concrete changes from the artifact named `#{documenter_agent.artifact_ref(:files_diffs)}`
+
+                - Understand what was the intent of the developer implementing those requirements.
+              EO_STEP
+              <<~EO_STEP,
+                Decide if documentation is needed
+
+                Before making any change, classify the development:
+
+                - If the change affects:
+                  - Features
+                  - Usage
+                  - APIs
+                  - Behavior visible to users
+                  → Documentation update MAY be required
+
+                - If the change is:
+                  - Internal refactor
+                  - Cleanup (removal of useless content)
+                  - Formatting
+                  - Documentation-only removal of irrelevant info
+                  → NO documentation update is required
+
+                If no documentation is required:
+                → STOP and do nothing
+              EO_STEP
+              <<~EO_STEP,
+                Explore the filesystem to locate documentation files
+
+                Guidelines:
+                - Start with README.md and docs/**/*.md if they exist.
+                - Look for files mentioning related features or APIs.
+                - Find documentation files that are referenced recursively from other documentation files.
+                - Understand the documentation structure and content.
+                - If no relevant documentation is found, proceed by assuming documentation needs to be created or extended.
+                - If you are unsure which documentation file to update: default to updating README.md.
+
+                This step is best-effort and should not block progress.
+              EO_STEP
+              <<~EO_STEP
+                Update the relevant documentation files
+
+                - Only perform this step if you think documentation is required.
+                - Use artifacts as the source of truth for understanding the changes to be documented.
+                - Use the filesystem to locate where documentation should be updated.
+                - After exploring the filesystem, if relevant documentation files are found: update them.
+
+                When updating documentation:
+                - Modify existing sections if they already describe related functionality.
+                - Add new sections if the feature is not documented.
+                - Keep consistency with existing documentation style.
+                - Prefer minimal, precise updates over large rewrites.
+              EO_STEP
+            ]
+          }
+        )
+        puts "===== Documenter changes: #{Helpers.git.status.changed.keys.join(', ')}"
+
+        if @commit || @pull_request
+          step_agent(
+            new_agent(
+              CommitterAgent,
+              user_review: false,
+              stage: :all,
+              authors: (@commit ? [] : [coder_agent, tester_agent]) + [documenter_agent]
+            )
+          )
+        end
+
+        if @pull_request
+          step_agent(
+            new_agent(
+              PullRequestCreatorAgent,
+              authors: [
+                planner_agent.plan_generator_agent,
+                coder_agent,
+                tester_agent,
+                documenter_agent
+              ]
+            )
+          )
+        end
+
+        puts
+        puts 'Requirements implemented successfully'
+
+        @artifacts
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/agents/diff_interpreter_agent.rb

@@ -0,0 +1,80 @@
+module XAeonAgents
+  module Agents
+    # Agent responsible for analyzing files differences in a repository
+    class DiffInterpreterAgent < ComposableAgents::AiAgents::Agent
+      prepend AgentDefaults
+
+      # Define input artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
+      def input_artifacts_contracts
+        super.merge(files_diff: 'The full list of files changes and differences that have been done')
+      end
+
+      # Define output artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of output artifacts description, per artifact name
+      def output_artifacts_contracts
+        super.merge(
+          change_intent: {
+            description: 'The full explanation of the changes, as in a git commit description',
+            type: :text
+          }
+        )
+      end
+
+      # Constructor
+      #
+      # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+      def initialize(**agent_params)
+        super(
+          name: 'Diff interpreter',
+          role: 'You are a files diff interpreter agent',
+          objective: <<~EO_OBJECTIVE,
+            Interpret files modifications and explain the changes properly with its meaning and intent.
+
+            The goals are:
+            - Get a general explanation of those changes.
+            - Identify the kind of changes involved (new features, feature change, bug fix, documentation...).
+            - Identify the components that are impacted by those changes (a specific plugin, CLI, UI...).
+          EO_OBJECTIVE
+          **agent_params
+        )
+        self.system_instructions = {
+          ordered_list: [
+            <<~EO_INSTRUCTIONS,
+              Read and analyze ALL file changes from the artifact named `#{artifact_ref(:files_diff)}`
+
+              - Those changes are the ones you must explain.
+            EO_INSTRUCTIONS
+            <<~EO_INSTRUCTIONS,
+              Analyze the project files
+
+              - Those files give you context to understand the changes.
+              - Changes made on those files should NOT be explained unless they are part of the artifact named `#{artifact_ref(:files_diff)}`.
+            EO_INSTRUCTIONS
+            <<~EO_INSTRUCTIONS
+              Create an artifact named `#{artifact_ref(:change_intent)}` to explain properly the changes reported by the artifact named `#{artifact_ref(:files_diff)}`
+
+              - You MUST create an artifact named `change_intent` that contains:
+                1. A general explanation of the changes, their meaning and intent in the context of this project.
+                2. The types of changes (feature, bug fix, documentation, etc.).
+                3. The impacted architectural components (backend, login screen, CLI, etc.).
+              - Describe those changes in a way similar to a git commit comment or a pull request description.
+              - ONLY cover changes from the artifact named `#{artifact_ref(:files_diff)}`.
+              - Do NOT explain changes for other files.
+            EO_INSTRUCTIONS
+          ]
+        }
+        self.constraints = <<~EO_CONSTRAINTS
+          - You are in read-only mode.
+          - Do NOT modify or write any file.
+          - You must ONLY explain the changes of the artifact named `#{artifact_ref(:files_diff)}`, NOT other changes.
+          - You already have ALL the information required.
+          - The user's intent is fully specified.
+          - The conversation log is provided for context only. You MUST NOT ask follow-up questions.
+        EO_CONSTRAINTS
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/agents/documenter_agent.rb

@@ -0,0 +1,44 @@
+module XAeonAgents
+  module Agents
+    # Agent responsible for updating documentation after a new development
+    class DocumenterAgent < ComposableAgents::Cline::Agent
+      prepend AgentDefaults
+
+      # Define input artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
+      def input_artifacts_contracts
+        super.merge(
+          requirements: 'The initial requirements',
+          plan: 'Implementation plan that introduced features and fixes to be documented',
+          files_diffs: 'Full list of files changes and differences that have been done to implement the initial requirements following the implementation plan'
+        )
+      end
+
+      # Constructor
+      #
+      # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+      def initialize(**agent_params)
+        super(
+          name: 'Documenter',
+          objective: 'Ensure documentation reflects the current product behavior and usage after a new development.',
+          constraints: <<~EO_CONSTRAINTS,
+            - Only update documentation files.
+            - Do NOT change any code or test.
+            - NEVER document the fact that a change happened.
+            - NEVER explain that something was removed, renamed, or fixed.
+            - Documentation describes the CURRENT STATE only.
+            - Documentation is NOT a changelog.
+          EO_CONSTRAINTS
+          skills: %w[
+            applying-ruby-conventions
+            applying-test-conventions
+            updating-doc
+            enforcing-project-rules
+          ],
+          **agent_params
+        )
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/agents/executor_agent.rb

@@ -0,0 +1,9 @@
+module XAeonAgents
+  module Agents
+    # Simple AI agent executing some prompt and interacting with the user
+    class ExecutorAgent < ComposableAgents::AiAgents::Agent
+      prepend ComposableAgents::Mixins::UserInteraction
+      prepend AgentDefaults
+    end
+  end
+end