x_aeon_agents 1.0.28

data/lib/x_aeon_agents/agents/feedback_analyst_agent.rb

@@ -0,0 +1,62 @@
+module XAeonAgents
+  module Agents
+    # Agent responsible for extracting requirements from PR comments directed at X-Aeon Agents
+    class FeedbackAnalystAgent < 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(
+          pr_description: 'The Pull Request description (context)',
+          pr_files_diffs: 'The files modifications that were done in this Pull Request (context)',
+          conversations: {
+            description: 'All Pull Request conversations and comments to be considered (context)',
+            type: :json
+          },
+          open_comments_to_agents: {
+            description: 'The exact list of agent-directed comments that need to be addressed',
+            type: :json
+          }
+        )
+      end
+
+      # Define output artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of output artifacts description, per artifact name
+      def output_artifacts_contracts
+        super.merge(
+          requirements: {
+            description: 'The requirements that will implement what is needed by the agent-directed comments ' \
+              '(reply "No requirements" if there is no implementation needed)',
+            type: :markdown
+          }
+        )
+      end
+
+      # Constructor
+      #
+      # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+      def initialize(**agent_params)
+        super(
+          name: 'FeedbackAnalyst',
+          role: 'You are a feedback analyst agent, analyzing feedback from a Pull Request and devising new requirements to address this feedback.',
+          objective: 'Extract requirements from Pull Request comments',
+          constraints: <<~EO_CONSTRAINTS,
+            - You are in read-only mode.
+            - Do NOT modify or write any file.
+            - Focus only on agent-directed comments (/agent) for requirement extraction.
+            - Output clear, actionable requirements or "No requirements" if none exist.
+          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/gh_comments.gql

@@ -0,0 +1,64 @@
+# Schema: https://raw.githubusercontent.com/octokit/graphql-schema/master/schema.graphql
+
+query FetchReviewComments($owner: String!, $repo: String!, $pr: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      url
+      reviewDecision
+      reviewThreads(first: 100) {
+        edges {
+          node {
+            isResolved
+            comments(first: 100) {
+              totalCount
+              nodes {
+                databaseId
+                pullRequestReview {
+                  createdAt
+                  author {
+                    login
+                  }
+                  body
+                  commit {
+                    oid
+                    message
+                  }
+                }
+                url
+                createdAt
+                state
+                replyTo {
+                  databaseId
+                  createdAt
+                  author {
+                    login
+                  }
+                  body
+                }
+                author {
+                  login
+                }
+                body
+                subjectType
+                path
+                commit {
+                  oid
+                  message
+                }
+                line
+                startLine
+                originalCommit {
+                  oid
+                  message
+                }
+                originalLine
+                originalStartLine
+                diffHunk
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

data/lib/x_aeon_agents/agents/git_diff_interpreter_agent.rb

@@ -0,0 +1,57 @@
+module XAeonAgents
+  module Agents
+    # Agent responsible for analyzing git differences with a given git ref base.
+    # The git ref base is given in the git_ref_base input artifact.
+    # For the staging area diff, use cached as the git_ref_base content.
+    class GitDiffInterpreterAgent < ComposableAgents::Agent
+      prepend AgentDefaults
+
+      # Define input artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
+      def input_artifacts_contracts
+        { git_ref_base: 'Git reference used to diff with' }
+      end
+
+      # Define output artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of output artifacts description, per artifact name
+      def output_artifacts_contracts
+        {
+          change_intent: 'Full description of the code changes, their meaning and intent',
+          one_line_summary: '1-line summary of the code change intent'
+        }
+      end
+
+      # Constructor
+      #
+      # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+      def initialize(**agent_params)
+        super(name: 'Git Diff Interpreter', **agent_params)
+      end
+
+      # Execute the agent to generate some output artifacts based on some input artifacts.
+      #
+      # @param git_ref_base [String] The git reference to diff with. Use 'cached' for the staging area.
+      # @return [Hash{Symbol => Object}] Output artifacts content
+      def run(git_ref_base:)
+        step_agent(
+          diff_interpreter_agent,
+          files_diff: Helpers.artifact_files_diffs(git_ref_base == 'cached' ? :cached : git_ref_base)
+        )
+        step_agent(new_agent(OneLineCodeDiffSummarizerAgent, **Config.agent_options['free_simple']))
+        {
+          change_intent: @artifacts[:change_intent],
+          one_line_summary: @artifacts[:one_line_summary]
+        }
+      end
+
+      # Get a Diff Interpreter agent.
+      #
+      # @return [Agent] The Diff Interpreter agent
+      def diff_interpreter_agent
+        @diff_interpreter_agent ||= new_agent(DiffInterpreterAgent, **Config.agent_options['free_simple'])
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/agents/issue_implementer_agent.rb

@@ -0,0 +1,88 @@
+module XAeonAgents
+  module Agents
+    # Agent responsible for implementing a GitHub issue using AI.
+    class IssueImplementerAgent < ComposableAgents::Agent
+      prepend AgentDefaults
+
+      # Define input artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
+      def input_artifacts_contracts
+        { github_issue_number: 'GitHub issue number to implement' }
+      end
+
+      # Constructor
+      #
+      # @param commit [Boolean] Whether to commit changes automatically
+      # @param pull_request [Boolean] Whether to create a pull request automatically
+      # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+      def initialize(commit: false, pull_request: false, **agent_params)
+        super(name: 'Issue Implementer', **agent_params)
+        @commit = commit
+        @pull_request = pull_request
+      end
+
+      # Execute the agent to implement a GitHub issue.
+      #
+      # @param github_issue_number [Integer] The GitHub issue number
+      # @return [Hash{Symbol => Object}] Output artifacts content
+      def run(github_issue_number:)
+        raise 'Unable to find the Github repository' unless Helpers.github_repo
+
+        issue = Helpers.github.issue(Helpers.github_repo, github_issue_number)
+        issue_comments = Helpers.github.issue_comments(Helpers.github_repo, github_issue_number)
+        sections = [
+          <<~EO_SECTION
+            # #{issue.title}
+
+            #{ComposableAgents::Utils::Markdown.align_markdown_headers(issue.body, level: 2)}
+          EO_SECTION
+        ]
+        unless issue_comments.empty?
+          sections << <<~EO_SECTION
+            # Comments
+
+            This is the conversation log that happened in this issue.
+            This is provided as a reference to better understand the requirements.
+
+            #{format_comments_for_artifact(issue_comments)}
+          EO_SECTION
+        end
+        issue_properties = ["Number: #{issue.number}"]
+        issue_properties << "Labels: #{issue.labels.map(&:name).join(', ')}" unless issue.labels.empty?
+        issue_properties.push(
+          "State: #{issue.state}",
+          "URL: #{issue.html_url}"
+        )
+        sections << <<~EO_SECTION
+          # Associated Github issue
+
+          #{issue_properties.map { |line| "- #{line}" }.join("\n")}
+        EO_SECTION
+        step_agent(
+          new_agent(DeveloperAgent, commit: @commit, pull_request: @pull_request),
+          requirements: sections.map(&:strip).join("\n\n")
+        )
+        {}
+      end
+
+      private
+
+      # Format issue comments for use in artifacts.
+      #
+      # @param comments [Array<Octokit::IssueComment>] Comments to format
+      # @return [String] Formatted comments as markdown
+      def format_comments_for_artifact(comments)
+        return 'No comments' if comments.empty?
+
+        comments.sort_by(&:created_at).map do |comment|
+          <<~EO_COMMENT
+            ## #{comment.user.login} at #{comment.created_at.utc.strftime('%F %T UTC')}
+
+            #{ComposableAgents::Utils::Markdown.align_markdown_headers(comment.body, level: 3)}
+          EO_COMMENT
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/agents/one_line_code_diff_summarizer_agent.rb

@@ -0,0 +1,57 @@
+module XAeonAgents
+  module Agents
+    # Agent responsible for summarizing code change intent into a single line
+    class OneLineCodeDiffSummarizerAgent < 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(change_intent: 'Full description of the code changes, their meaning and intent')
+      end
+
+      # Define output artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of output artifacts description, per artifact name
+      def output_artifacts_contracts
+        super.merge(one_line_summary: '1-line summary of the code change intent')
+      end
+
+      # Constructor
+      #
+      # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+      def initialize(**agent_params)
+        super(
+          name: '1-line code diff summarizer',
+          role: 'You are a 1-line code diff summarizer agent',
+          objective: 'Produce a 1-line summary of a code change intent report.',
+          constraints: <<~EO_CONSTRAINTS,
+            - You are in read-only mode.
+            - Do NOT modify or write any file.
+            - You already have ALL the information required.
+            - The user's intent is fully specified.
+            - You MUST NOT ask follow-up questions.
+          EO_CONSTRAINTS
+          **agent_params
+        )
+        self.system_instructions = {
+          ordered_list: [
+            <<~EO_INSTRUCTIONS,
+              Read the artifact named `#{artifact_ref(:change_intent)}` to understand what you need to summarize
+
+              - This artifact contains already all the information you need to summarize.
+              - You don't need to gather more information thatn this.
+            EO_INSTRUCTIONS
+            <<~EO_INSTRUCTIONS
+              Create an artifact named `#{artifact_ref(:one_line_summary)}` to provide a 1-line summary of the code change intent described in the artifact named `#{artifact_ref(:change_intent)}`
+
+              - Summarize the change intent the same way you would write a git commit comment title.
+              - Follow standard git commit title conventions using `feat`, `fix`, etc... with impacted component names.
+            EO_INSTRUCTIONS
+          ]
+        }
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/agents/plan_generator_agent.rb

@@ -0,0 +1,51 @@
+module XAeonAgents
+  module Agents
+    # Agent responsible for producing detailed implementation plans from requirements
+    class PlanGeneratorAgent < 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 for which you need to devise an implementation plan')
+      end
+
+      # Define output artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of output artifacts description, per artifact name
+      def output_artifacts_contracts
+        super.merge(
+          plan: {
+            description: 'The full and detailed implementation plan in Markdown format, ' \
+              "that should implement the requirements given by the artifact named `#{artifact_ref(:requirements)}`",
+            type: :markdown
+          }
+        )
+      end
+
+      # Constructor
+      #
+      # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+      def initialize(**agent_params)
+        super(
+          name: 'Planner',
+          role: 'You are a Planner agent',
+          objective: 'Produce a full and detailed implementation plan that can be used to implement some requirements.',
+          constraints: <<~EO_CONSTRAINTS,
+            - You are in read-only mode.
+            - Do NOT modify or write any file.
+            - You may only analyze and propose plans.
+            - Do NOT execute the plan yourself.
+          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/planner_agent.rb

@@ -0,0 +1,89 @@
+module XAeonAgents
+  module Agents
+    # Agent responsible for producing an implementation plan acceptable to the user.
+    class PlannerAgent < 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 for which you need to devise an implementation plan' }
+      end
+
+      # Define output artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of output artifacts description, per artifact name
+      def output_artifacts_contracts
+        {
+          plan: {
+            description: 'The full and detailed implementation plan in Markdown format, ' \
+              "that should implement the requirements given by the artifact named `#{plan_generator_agent.artifact_ref(:requirements)}`",
+            type: :markdown
+          }
+        }
+      end
+
+      # Execute the agent to generate some output artifacts based on some input artifacts.
+      #
+      # @param requirements [String] The initial requirements.
+      # @return [Hash{Symbol => Object}] Output artifacts content
+      def run(requirements:)
+        user_instructions = {
+          ordered_list: [
+            "Read the initial requirements from the artifact named `#{plan_generator_agent.artifact_ref(:requirements)}`",
+            'Analyze the project files',
+            "Create an artifact named `#{plan_generator_agent.artifact_ref(:plan)}` with a complete and detailed " \
+              'step-by-step implementation plan in Markdown format'
+          ]
+        }
+        loop do
+          step_agent(plan_generator_agent, user_instructions:)
+          @artifacts[:plan].strip!
+          content, user_prompt = Helpers.review_content(
+            reviews_dir: "#{@session_dir}/reviews",
+            name: 'plan.md',
+            description: 'Implementation plan',
+            editable: true,
+            promptable: true,
+            content: @artifacts[:plan]
+          )
+          diffs =
+            if @artifacts[:plan] == content
+              nil
+            else
+              Diffy::Diff.new("#{@artifacts[:plan].strip}\n", "#{content.strip}\n", context: 3, include_diff_info: true).to_s
+            end
+          @artifacts[:plan] = content
+          break if user_prompt.empty?
+
+          user_instructions = <<~EO_INSTRUCTIONS
+            #{user_prompt}
+
+            Re-create the artifact named `#{plan_generator_agent.artifact_ref(:plan)}` with a revised implementation plan, taking the above user guidance into account.
+          EO_INSTRUCTIONS
+          user_instructions << <<~EO_INSTRUCTIONS if diffs
+
+            The user performed the following modifications on your implementation plan.
+            You have to take them into account while revising the plan.
+
+            ```
+            #{
+              # Remove the 2 first lines (headers of temporary file names).
+              diffs.to_s.split("\n")[2..].join("\n").strip
+            }
+            ```
+          EO_INSTRUCTIONS
+        end
+        { plan: @artifacts[:plan] }
+      end
+
+      # Get a Plan Generator agent.
+      #
+      # @return [Agent] The Plan Generator agent
+      def plan_generator_agent
+        @plan_generator_agent ||= new_agent(PlanGeneratorAgent, **Config.agent_options['free_complex_planning'])
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/agents/pull_request_creator_agent.rb

@@ -0,0 +1,144 @@
+module XAeonAgents
+  module Agents
+    # Agent responsible for creating a Pull Request of the current branch against its base reference on Github.
+    class PullRequestCreatorAgent < ComposableAgents::Agent
+      prepend AgentDefaults
+
+      # Define input artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of input artifacts description, per artifact name
+      def input_artifacts_contracts
+        {
+          base_sha: 'The git ref of the base of the feature branch',
+          requirements: {
+            description: 'The initial requirements',
+            optional: true
+          }
+        }
+      end
+
+      # Constructor
+      #
+      # @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(authors: [], **agent_params)
+        super(name: 'Pull Request Creator', **agent_params)
+        @authors = authors
+      end
+
+      # Execute the agent to generate some output artifacts based on some input artifacts.
+      #
+      # @param base_sha [String] The git reference of the base of the branch.
+      # @param requirements [String, nil] The initial requirements, or nil if none.
+      # @return [Hash{Symbol => Object}] Output artifacts content
+      def run(base_sha:, requirements: nil)
+        raise 'Unable to find the Github repository' unless Helpers.github_repo
+
+        repo_name = Helpers.github_repo
+        head_branch = Helpers.git.current_branch
+
+        # Push the branch on the git_remote using --force-with-lease as it may have been rebased
+        # TODO: Use force_with_lease when it will be supported by ruby-git
+        Helpers.git.push(Helpers.github_remote, head_branch, force: true)
+
+        # Check if PR already exists for the current branch
+        existing_pr = Helpers.github.pull_requests(repo_name, state: 'open').find { |pull_request| pull_request.head.ref == head_branch }
+        if existing_pr.nil?
+          # Create new PR
+          git_diff_interpreter_agent = new_agent(GitDiffInterpreterAgent)
+          step_agent(git_diff_interpreter_agent, git_ref_base: base_sha)
+          step(:create_pr) do
+            sections = [@artifacts[:change_intent].strip]
+            sections << <<~EO_SECTION if requirements
+              # Initial requirements given
+
+              #{ComposableAgents::Utils::Markdown.align_markdown_headers(requirements, level: 2)}
+            EO_SECTION
+            full_messages = @authors
+              .map do |author|
+                if author.respond_to?(:conversation)
+                  # Only keep single user prompts and agent's questions with their corresponding user's answer
+                  messages = []
+                  # Skip the first user instruction
+                  remaining_conversation =
+                    if !author.conversation.empty? && author.conversation.first[:author].downcase == 'user'
+                      author.conversation[1..]
+                    else
+                      author.conversation
+                    end
+                  until remaining_conversation.empty?
+                    message = remaining_conversation.shift
+                    next if message[:message].strip.empty?
+
+                    if message[:author].downcase == 'user'
+                      messages << message
+                    elsif message[:question]
+                      answer = remaining_conversation.first
+                      messages <<
+                        if answer && answer[:author].downcase == 'user' && !answer[:message].strip.empty?
+                          message.merge(answer: remaining_conversation.shift)
+                        else
+                          message
+                        end
+                    end
+                  end
+                  messages
+                else
+                  []
+                end
+              end
+              .flatten(1)
+              .sort_by { |message| message[:at] }
+            sections << <<~EO_SECTION unless full_messages.empty?
+              # User guidance and feedback to agents
+
+              #{
+                full_messages
+                  .map do |message|
+                    <<~EO_MESSAGE.strip
+                      › **#{message[:author]}**
+                      #{message[:message].each_line.map { |line| "> #{line}".strip }.join("\n")}
+                      > <sub>#{message[:at]}</sub>
+                      #{
+                        if message[:answer]
+                          <<~EO_ANSWER
+                            >
+                            > › **#{message[:answer][:author]}**
+                            #{message[:answer][:message].each_line.map { |line| "> &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;#{line}" }.join("\n")}
+                            > &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<sub>#{message[:answer][:at]}</sub>
+                          EO_ANSWER
+                        end
+                      }
+                    EO_MESSAGE
+                  end
+                  .join("\n\n")
+              }
+            EO_SECTION
+            sections << <<~EO_SECTION unless @authors.empty?
+              # 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_SECTION
+            new_pr = Helpers.github.create_pull_request(
+              repo_name,
+              base_sha,
+              head_branch,
+              @artifacts[:one_line_summary].strip,
+              sections.map(&:strip).join("\n\n")
+            )
+            # TODO: Make that a log_info
+            log_debug "Created new Pull Request for branch #{head_branch}: #{new_pr.html_url}"
+          end
+        else
+          # TODO: Make that a log_info
+          log_debug "A Pull Request for branch #{head_branch} already exists: #{existing_pr.html_url}"
+        end
+        {}
+      end
+    end
+  end
+end

data/lib/x_aeon_agents/agents/readme/about_analyzer_agent.rb

@@ -0,0 +1,55 @@
+module XAeonAgents
+  module Agents
+    # Collection of agents used to generate README parts
+    module Readme
+      # Agent responsible for generating the "About" section of a README.
+      class AboutAnalyzerAgent < ComposableAgents::Cline::Agent
+        prepend AgentDefaults
+
+        # Define output artifacts contracts
+        #
+        # @return [Hash{Symbol => Object}] Set of output artifacts description, per artifact name
+        def output_artifacts_contracts
+          super.merge(
+            about: {
+              description: 'The "About" section content in Markdown format, describing the project goal, problem it solves, and its interface',
+              type: :markdown
+            },
+            name: {
+              description: 'This project\'s name',
+              type: :text
+            },
+            description: {
+              description: 'This project\'s description in 1 line',
+              type: :markdown
+            }
+          )
+        end
+
+        # Constructor
+        #
+        # @param agent_params [Hash{Symbol => Object}] Extra agent parameters
+        def initialize(**agent_params)
+          super(
+            name: 'About Analyzer',
+            objective: <<~EO_OBJECTIVE,
+              Analyze the project's code, features and layout to understand its purpose and interface.
+              Provide the following information:
+              - The project's name (for example Rubygem's name, released package name, repository's name...).
+              - The 1-line description of the project, using Markdown.
+              - A high-level overview (about section) of the project in Markdown format, compatible with Github flavor.
+            EO_OBJECTIVE
+            constraints: <<~EO_CONSTRAINTS,
+              - The required output artifacts content should only contain the required content, without additional header or title.
+              - Do not explain or describe the artifact contents: only provide the content as required.
+              - Only focus on the specific scope of the required documentation required.
+                Other agents will generate other sections of the README.
+                Do not try to document other parts.
+            EO_CONSTRAINTS
+            **agent_params
+          )
+        end
+      end
+    end
+  end
+end