composable_agents 1.0.0

data/lib/composable_agents/cline/agent.rb

@@ -0,0 +1,246 @@
+require 'cline'
+
+module ComposableAgents
+  # All agents from this module work with the awesome cline-rb Rubygem
+  module Cline
+    # Missin skill error
+    class MissingSkillError < RuntimeError
+    end
+
+    # Agent implementation that uses an ai-agent's AgentRunner.
+    class Agent < PromptDrivenAgent
+      # @!group Public API
+
+      prepend Mixins::ArtifactContract
+
+      # Initialize a new agent that uses the Cline CLI in a dedicated config
+      #
+      # @param strategy [Module] The prompt rendering strategy
+      # @param provider [String] Provider to be used
+      # @param model [String] Model to be used
+      # @param api_key [String] API key to be used
+      # @param configure_provider [#call(provider_settings), nil] Optional block used to configure the provider settings
+      #   * Param provider_settings [Cline::Providers::ProviderSettings] Settings that can be tuned for this agent
+      # @param configure_global [#call(global_settings), nil] Optional block used to configure the global settings
+      #   * Param global_settings [Cline::GlobalSettings] Settings that can be tuned for this agent
+      # @param skills [Array<String>] List of skills to allow for this agent
+      # @param cli_options [Hash{Symbol => Object}] Task options to give to Cline CLI (see Cline::Cli.COMMANDS)
+      def initialize(
+        *args,
+        strategy: PromptRenderingStrategy::MarkdownHeavy,
+        provider: 'cline',
+        model: 'anthropic/claude-sonnet-4.6',
+        api_key: ENV.fetch('CLINE_API_KEY', nil),
+        configure_provider: nil,
+        configure_global: nil,
+        skills: [],
+        cli_options: {},
+        **kwargs
+      )
+        super(*args, strategy:, **kwargs)
+        @provider = provider
+        @model = model
+        @api_key = api_key ? ::Cline::SecretString.new(api_key.dup) : nil
+        @configure_provider = configure_provider
+        @configure_global = configure_global
+        @skills = skills
+        @cli_options = cli_options
+        @context = []
+      end
+
+      # Return the full name of the agent.
+      # This method is intended to be overridden by subclasses to give better full names, tailored to the kind of agent.
+      # The full name can be used in logs and traces to better identify the agent.
+      #
+      # @return [String] The agent's full name
+      def full_name
+        "#{name || 'Unnamed'} (Cline #{@provider}/#{@model})"
+      end
+
+      # @!group Internal
+
+      # Export the agent state for persistence
+      #
+      # @return [Object] Serialized state that can be marshalled to JSON
+      def export_state
+        super.merge(deep_transform_keys(context: @context, &:to_s))
+      end
+
+      # Import the agent state from persistence
+      #
+      # @param state [Object] Serialized state
+      def import_state(state)
+        super
+        @context = deep_transform_keys(state, &:to_sym)[:context]
+      end
+
+      private
+
+      # Process a user prompt.
+      #
+      # @param user_prompt [String] The rendered user prompt
+      # @return [String] The output of the prompt
+      def prompt(user_prompt)
+        # Add the context to the prompt if it is the first prompt of this Cline CLI session
+        full_user_prompt =
+          if @context.empty?
+            user_prompt
+          else
+            <<~EO_SECTION
+              # Previous sessions context
+
+              Here is the conversation from a previous session for context:
+
+              ```json
+              #{JSON.dump(@context)}
+              ```
+
+              Continue with the task, building on the work from the session above.
+
+              #{user_prompt}
+            EO_SECTION
+          end
+        # Call the Cline CLI
+        result = cline_cli.task(
+          full_user_prompt,
+          system: @system_prompt,
+          on_question: respond_to?(:ask, true) ? proc { |question| ask(question) } : nil,
+          on_message: proc do |message, _last, _previous_version|
+            # Look for any output artifact from the answers
+            if message.role == 'assistant'
+              message.content&.each do |content|
+                parse_output_artifacts(content.text) if content.type == 'text' && content.text
+              end
+            end
+          end,
+          **@cli_options
+        )
+        raise "Error: #{result[:error].err.message}".strip if result[:error]
+
+        # Keep the context in case we need to resume it
+        if cline_cli.session&.messages
+          @context.concat(
+            cline_cli.session.messages.map.with_index do |message, idx_message|
+              {
+                role: message.role,
+                content: message.content.map.with_index do |content, idx_content|
+                  {
+                    type: content.type,
+                    text: (
+                      if idx_message.zero? && idx_content.zero?
+                        # First message is the user prompt, but we don't want to include the context from it
+                        user_prompt
+                      else
+                        content.text
+                      end
+                    ),
+                    input:
+                      if content.input
+                        {
+                          question: content.input.question,
+                          options: content.input.options
+                        }.compact
+                      end,
+                    content: content.content
+                  }.compact
+                end
+              }
+            end
+          )
+        end
+
+        result[:message]&.content&.last&.text || ''
+      end
+
+      # Get the Cline CLI instance to use for this agent.
+      # Memoize it.
+      #
+      # @return [::Cline::Cli] The Cline CLI instance to be used
+      def cline_cli
+        @cline_cli ||= begin
+          # Resolve all the skills and their dependencies (taken from their YAML front matter).
+          selected_skills = []
+          @skills.each do |skill|
+            find_skill(skill, selected_skills)
+          end
+          # Setup the temporary Cline global config dir
+          agent_tmp_dir = "#{@composable_agents_dir}/tmp/#{Time.now.utc.strftime('%F-%H-%M-%S')}#{"-#{name.gsub(/[^\w.]/, '_')}" if name}"
+          ::Cline.configure do |config|
+            config.debug = Mixins::Logger.debug?
+            config.temp_dir_root = "#{agent_tmp_dir}/cline-rb"
+          end
+          cline_config = ::Cline::Config.open("#{agent_tmp_dir}/cline_config", create: true)
+          # Copy all selected global skills in this config's skills
+          if ::Cline::Config.global&.skills
+            (::Cline::Config.global.skills.keys & selected_skills).each do |skill_name|
+              new_skill = cline_config.skills.new(skill_name)
+              new_skill.files.replace(::Cline::Config.global.skills[skill_name].files)
+              new_skill.enable
+              log_debug "[Cline] - Enable global skill #{skill_name}"
+              new_skill.save
+            end
+          end
+          # Enable/disable project skills to make sure only selected ones are enabled
+          ::Cline::Config.project&.skills&.each do |skill_name, skill|
+            selected_skill = selected_skills.include?(skill_name)
+            next if skill.enabled? == selected_skill
+
+            if selected_skill
+              log_debug "[Cline] - Enable project skill #{skill_name}"
+              skill.enable
+            else
+              log_debug "[Cline] - Disable project skill #{skill_name}"
+              skill.disable
+            end
+            skill.save
+          end
+          # TODO: When using skillkit, also create a global rule only containing selected skills (use skillkit if possible to generate it).
+          #   Or maybe just don't use skillkit to generate this AGENTS.md file. Skills should be discoverable without it. To be tested.
+          # Set the configuration
+          providers = cline_config.providers(create: true)
+          providers.version = 1
+          providers.last_used_provider = @provider
+          providers.providers = {
+            @provider => {
+              token_source: 'manual',
+              updated_at: Time.now.utc.strftime('%FT%T.%LZ'),
+              settings: {
+                provider: @provider,
+                api_key: @api_key,
+                model: @model
+              }
+            }
+          }
+          @configure_provider&.call(providers.providers[@provider].settings)
+          providers.save
+          global_settings = cline_config.global_settings(create: true)
+          # Don't update the Cline CLI
+          global_settings.auto_update_enabled = false
+          @configure_global&.call(global_settings)
+          global_settings.save
+          cline_config.cli(stdout_echo: Mixins::Logger.debug?, verbose: Mixins::Logger.debug?)
+        end
+      end
+
+      # Find a skill among the current Cline environment (global and project) and recursively finds all its dependencies.
+      #
+      # @param skill [String] The skill name we are looking for
+      # @param found_skills [Array<String>] In place list of skills that are already found (so we don't need to look for them again)
+      #   If found, the skill and its dependencies will be added to this array.
+      def find_skill(skill, found_skills)
+        return if found_skills.include?(skill)
+
+        # Find the skill among the global or local configs
+        found_skill = (::Cline::Config.global&.skills && ::Cline::Config.global.skills[skill]) ||
+          (::Cline::Config.project&.skills && ::Cline::Config.project.skills[skill])
+        raise MissingSkillError, "Cline Skill #{skill} is unknown, neither in the global nor project configurations" unless found_skill
+
+        found_skills << skill
+        # Now look for its dependencies
+        (found_skill.yaml_front_matter.dig(*%i[metadata dependencies]) || []).each do |skill_dep|
+          find_skill(skill_dep, found_skills)
+        end
+      end
+    end
+  end
+end

data/lib/composable_agents/instructions.rb

@@ -0,0 +1,42 @@
+module ComposableAgents
+  # Provide a way to define instructions to be used by system and user prompts.
+  # Instructions are always normalized as a list of individual instructions that each can be rendered differently depending on the rendering strategy.
+  # This is used by PromptDrivenAgent agents only.
+  class Instructions
+    # @!group Public API
+
+    include Enumerable
+
+    # Constructor
+    #
+    # @param instructions [Object] The instructions definition. Here are the possible kinds of system instructions:
+    #   - [Array<Object>] List of instruction descriptions that should be appended
+    #   - [Object] Individual instruction description.
+    #   An individual instruction can be one of the following:
+    #     - [String] Direct instructions to be used (equivalent to { text: instructions })
+    #     - [Hash\\{Symbol => Object}] A structure describing the instructions
+    #       Here is the list of keys that can define different instructions:
+    #       - text [String] The instructions are given as text directly.
+    #       - ordered_list [Array<String>] The instructions are a precise list of steps to perform.
+    #       Several keys can be used in the same Hash, and they will be treated in the order of the Hash.
+    def initialize(instructions)
+      # Normalize system instructions to [Array<Hash{Symbol => Object}>].
+      @instructions = (instructions.is_a?(Array) ? instructions : [instructions]).map do |instructions_set|
+        instructions_set.is_a?(Hash) ? instructions_set : { text: instructions_set }
+      end
+    end
+
+    # Iterate over all instructions
+    #
+    # @yield [instruction_type, instruction] Each instruction present in these instructions.
+    # @yieldparam instruction_type [Symbol] The instruction type.
+    # @yieldparam instruction [Object] The instruction itself.
+    def each(&)
+      return enum_for(:each) unless block_given?
+
+      @instructions.each do |instructions_set|
+        instructions_set.each(&)
+      end
+    end
+  end
+end

data/lib/composable_agents/mixins/ai_agent_user_interaction.rb

@@ -0,0 +1,23 @@
+module ComposableAgents
+  module Mixins
+    # Mixin that adds user interaction capabilities to AiAgent::Agent agents.
+    # This uses an AiAgent tool to then call the normal UserInteraction interface.
+    module AiAgentUserInteraction
+      # @!group Internal
+
+      # Hook used when this mixin is included in a base class
+      #
+      # @param base [Class] The base class
+      def self.prepended(base)
+        base.include(UserInteraction)
+      end
+
+      # Returns the list of tools available for this agent
+      #
+      # @return [Array<Agents::Tool>] List of tools
+      def agent_tools
+        super + [AiAgents::Tools::AskUserTool.new(self)]
+      end
+    end
+  end
+end

data/lib/composable_agents/mixins/artifact_contract.rb

@@ -0,0 +1,181 @@
+require 'json'
+
+module ComposableAgents
+  module Mixins
+    # Mixin providing input/output artifact validation functionality for Agents.
+    # The contracts should be provided by methods named #input_artifacts_contracts and #output_artifacts_contracts
+    # A contract can be one of the following objects:
+    # - [String] The artifact's description
+    # - [Hash\\{Symbol => Object}] The artifact's detailed contract. It can contain the following attributes:
+    #   - description [String] The artifact's description. This is also the default value when the contract is expressed as a [String].
+    #   - optional [Boolean] Is the artifact optional? Defaults to false.
+    #   - type [Symbol] The type of this artifact. Defaults to :text.
+    #     Possible values are:
+    #     - `text` for raw text.
+    #     - `markdown` for Markdown.
+    #     - `json` for JSON.
+    #     Type can be used by some agents to tailor their output format and prompts.
+    module ArtifactContract
+      # @!group Public API
+
+      # Raised when required input artifacts are missing
+      class MissingInputArtifactError < RuntimeError
+      end
+
+      # Raised when expected output artifacts are missing
+      class MissingOutputArtifactError < RuntimeError
+      end
+
+      # Raised when validations on artifact types are failing
+      class ArtifactTypeError < RuntimeError
+      end
+
+      # Constructor
+      #
+      # @param input_artifacts_contracts [Hash{Symbol => Object}, nil] Hash of input artifact names and their contracts,
+      #   or nil if provided through the input_artifacts_contracts method
+      # @param output_artifacts_contracts [Hash{Symbol => Object}, nil] Hash of output artifact names and their contracts,
+      #   or nil if provided through the output_artifacts_contracts method
+      def initialize(
+        *args,
+        input_artifacts_contracts: nil,
+        output_artifacts_contracts: nil,
+        **kwargs
+      )
+        super(*args, **kwargs)
+        @input_artifacts_contracts = input_artifacts_contracts
+        @output_artifacts_contracts = output_artifacts_contracts
+      end
+
+      # @!group Internal
+
+      # Execute the agent to generate some output artifacts based on some input artifacts.
+      #
+      # @param input_artifacts [Hash{Symbol => Object}] The input artifacts content
+      # @return [Hash{Symbol => Object}] Output artifacts content
+      # @raise [MissingInputArtifactError] If required input artifacts are missing
+      # @raise [MissingOutputArtifactError] If expected output artifacts are missing after run
+      def run(**input_artifacts)
+        validate_input_artifacts(input_artifacts)
+        output_artifacts = super(**input_artifacts.slice(*normalized_input_artifacts_contracts.keys))
+        validate_output_artifacts(output_artifacts)
+        output_artifacts
+      end
+
+      private
+
+      # Define input artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of input artifacts contract, per artifact name
+      def input_artifacts_contracts
+        # If the contracts were given by the constructor, use them
+        (defined?(super) ? super : {}).merge(@input_artifacts_contracts || {})
+      end
+
+      # Define output artifacts contracts
+      #
+      # @return [Hash{Symbol => Object}] Set of output artifacts contract, per artifact name
+      def output_artifacts_contracts
+        # If the contracts were given by the constructor, use them
+        (defined?(super) ? super : {}).merge(@output_artifacts_contracts || {})
+      end
+
+      # Normalize artifacts' contracts
+      #
+      # @param artifacts_contracts [Hash{Symbol => Object}] The artifacts contracts to be normalized
+      # @return [Hash{Symbol => Hash{Symbol => Object}}] The normalized artifacts contracts (always in their Hash form as described in the class documentation)
+      def normalize_contracts(artifacts_contracts)
+        artifacts_contracts.to_h do |art_name, contract_def|
+          contract_def = { description: contract_def } unless contract_def.is_a?(Hash)
+          [
+            art_name,
+            # Default values
+            {
+              description: 'Artifact',
+              optional: false
+            }.merge(contract_def)
+          ]
+        end
+      end
+
+      # Retrieve and memoize normalized input artifacts contracts
+      #
+      # @return [Hash{Symbol => Hash{Symbol => Object}}] Set of normalized input artifacts contract, per artifact name
+      def normalized_input_artifacts_contracts
+        @normalized_input_artifacts_contracts ||= normalize_contracts(input_artifacts_contracts)
+      end
+
+      # Retrieve and memoize normalized output artifacts contracts
+      #
+      # @return [Hash{Symbol => Hash{Symbol => Object}}] Set of normalized output artifacts contract, per artifact name
+      def normalized_output_artifacts_contracts
+        @normalized_output_artifacts_contracts ||= normalize_contracts(output_artifacts_contracts)
+      end
+
+      # Validate that all required input artifacts are present
+      #
+      # @param artifacts [Hash{Symbol => Object}] Input artifacts to validate
+      # @raise [MissingInputArtifactError] If any required artifacts are missing
+      def validate_input_artifacts(artifacts)
+        artifacts_contracts = normalized_input_artifacts_contracts.reject { |_name, contract| contract[:optional] }
+        missing_inputs = artifacts_contracts.keys - artifacts.keys
+        unless missing_inputs.empty?
+          raise MissingInputArtifactError, "Missing required input artifacts:\n#{
+            missing_inputs.map do |artifact_name|
+              "* #{artifact_name}: #{artifacts_contracts[artifact_name][:description]}"
+            end.join("\n")
+          }"
+        end
+        validate_artifacts_types(artifacts, normalized_input_artifacts_contracts)
+      end
+
+      # Validate that all expected output artifacts are present
+      #
+      # @param artifacts [Hash{Symbol => Object}] Output artifacts to validate
+      # @raise [MissingOutputArtifactError] If any expected artifacts are missing
+      def validate_output_artifacts(artifacts)
+        artifacts_contracts = normalized_output_artifacts_contracts.reject { |_name, contract| contract[:optional] }
+        missing_outputs = artifacts_contracts.keys - artifacts.keys
+        unless missing_outputs.empty?
+          raise MissingOutputArtifactError, "Agent failed to produce expected output artifacts:\n#{
+            missing_outputs.map do |key|
+              "* #{key}: #{artifacts_contracts[key][:description]}"
+            end.join("\n")
+          }"
+        end
+        validate_artifacts_types(artifacts, normalized_output_artifacts_contracts)
+      end
+
+      # Validate the types of the artifacts.
+      #
+      # @param artifacts [Hash{Symbol => Object}] The artifacts to validate
+      # @param artifacts_contracts [Hash{Symbol => Hash{Symbol => Object}}] The artifacts contracts
+      def validate_artifacts_types(artifacts, artifacts_contracts)
+        # Validate the types if provided
+        artifacts.each do |artifact_name, content|
+          required_type = artifacts_contracts.dig(artifact_name, :type)
+          next unless required_type
+
+          case required_type
+          when :text, :markdown
+            unless content.is_a?(String)
+              raise ArtifactTypeError, "Artifact #{artifact_name} should be a #{required_type} String but is actually a #{content.class.name}"
+            end
+          when :json
+            begin
+              unless JSON.parse(JSON.dump(content)) == content
+                raise ArtifactTypeError, "Artifact #{artifact_name} should be a JSON object but serializing it into JSON changed its data"
+              end
+            rescue StandardError => e
+              raise if e.is_a?(ArtifactTypeError)
+
+              raise ArtifactTypeError, "Artifact #{artifact_name} should be a JSON object but parsing it raised error: #{e}"
+            end
+          else
+            raise ArtifactTypeError, "Unknown artifact type: #{required_type}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/composable_agents/mixins/logger.rb

@@ -0,0 +1,47 @@
+module ComposableAgents
+  # Collection of useful mixins that add functionality to agents prepending them.
+  module Mixins
+    # Logging mixin for agents
+    module Logger
+      # @!group Public API
+
+      # Check if debug mode is enabled
+      #
+      # @return [Boolean] True if debug mode is enabled
+      def self.debug?
+        ENV['COMPOSABLE_AGENTS_DEBUG'] == '1'
+      end
+
+      private
+
+      # Log debug message only if debug mode is enabled
+      #
+      # @param message [String, Proc] Message string or Proc returning message for lazy evaluation
+      def log_debug(message)
+        return unless Logger.debug?
+
+        log(message, severity: :debug)
+      end
+
+      # Log info message
+      #
+      # @param message [String, #call => String] Message string or Proc returning message for lazy evaluation
+      def log_info(message)
+        log(message, severity: :info)
+      end
+
+      # Log a message with severity
+      #
+      # @param message [String, #call => String] Message string or Proc returning message for lazy evaluation
+      # @param severity [Symbol] Severity
+      def log(message, severity: :info)
+        fields = [
+          Time.now.utc.strftime('%F %T'),
+          severity.to_s.upcase
+        ]
+        fields.concat(log_fields) if respond_to?(:log_fields, true)
+        puts "#{fields.map { |field| "[#{field}]" }.join(' ')} - #{message.is_a?(String) ? message : message.call}"
+      end
+    end
+  end
+end