roast-ai 0.4.10 → 0.5.1

data/lib/roast/dsl/cogs/agent/config.rb

@@ -0,0 +1,465 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module Cogs
+      class Agent < Cog
+        class Config < Cog::Config
+          VALID_PROVIDERS = [:claude].freeze #: Array[Symbol]
+
+          # Configure the cog to use a specified provider when invoking an agent
+          #
+          # The provider is the source of the agent tool itself.
+          # If no provider is specified, Anthropic Claude Code (`:claude`) will be used as the default provider.
+          #
+          # A provider must be properly installed on your system in order for Roast to be able to use it.
+          #
+          # #### See Also
+          # - `use_default_provider!`
+          #
+          #: (Symbol) -> void
+          def provider(provider)
+            @values[:provider] = provider
+          end
+
+          # Configure the cog to use the default provider when invoking an agent
+          #
+          # The default provider used by Roast is Anthropic Claude Code (`:claude`).
+          #
+          # The provider must be properly installed on your system in order for Roast to be able to use it.
+          #
+          # #### See Also
+          # - `provider`
+          #
+          #: () -> void
+          def use_default_provider!
+            @values[:provider] = nil
+          end
+
+          # Get the validated provider name that the cog is configured to use when invoking an agent
+          #
+          # Note: this method will return the name of a valid provider or raise an `InvalidConfigError`.
+          # It will __not__, however, validate that the agent is properly installed on your system.
+          # If the agent is not properly installed, you will likely experience a failure when Roast attempts to
+          # run your workflow.
+          #
+          # #### See Also
+          # - `provider`
+          # - `use_default_provider!`
+          #
+          #: () -> Symbol
+          def valid_provider!
+            provider = @values[:provider] || VALID_PROVIDERS.first
+            unless VALID_PROVIDERS.include?(provider)
+              raise ArgumentError, "'#{provider}' is not a valid provider. Available providers include: #{VALID_PROVIDERS.join(", ")}"
+            end
+
+            provider
+          end
+
+          # Configure the cog to use a specific base command when invoking the agent
+          #
+          # The command format is provider-specific.
+          #
+          # #### See Also
+          # - `use_default_command!`
+          #
+          #: (String | Array[String]) -> void
+          def command(command)
+            @values[:command] = command
+          end
+
+          # Configure the cog to use the provider's default command when invoking the agent
+          #
+          # Note: the default command will be different for different providers.
+          #
+          # #### See Also
+          # - `command`
+          #
+          #: () -> void
+          def use_default_command!
+            @values[:command] = nil
+          end
+
+          # Get the validated, configured value of the command the cog is configured to use when running the agent
+          #
+          # Returns `nil` if the provider should use its own default command, however that is configured.
+          #
+          # #### See Also
+          # - `command`
+          # - `use_default_command!`
+          #
+          #: () -> (String | Array[String])?
+          def valid_command
+            @values[:command].presence
+          end
+
+          # Configure the cog to use a specific model when invoking the agent
+          #
+          # The model name format is provider-specific.
+          #
+          # #### See Also
+          # - `use_default_model!`
+          #
+          #: (String) -> void
+          def model(model)
+            @values[:model] = model
+          end
+
+          # Configure the cog to use the provider's default model when invoking the agent
+          #
+          # Note: the default model will be different for different providers.
+          #
+          # #### See Also
+          # - `model`
+          #
+          #: () -> void
+          def use_default_model!
+            @values[:model] = nil
+          end
+
+          # Get the validated, configured value of the model the cog is configured to use when running the agent
+          #
+          # Returns `nil` if the provider should use its own default model, however that is configured.
+          #
+          # #### See Also
+          # - `model`
+          # - `use_default_model!`
+          #
+          #: () -> String?
+          def valid_model
+            @values[:model].presence
+          end
+
+          # Configure the cog with an initial prompt component that will be appended to the agent's system prompt
+          # every time the agent is invoked
+          #
+          # #### See Also
+          # - `no_initial_prompt!`
+          #
+          #: (String) -> void
+          def initial_prompt(prompt)
+            @values[:initial_prompt] = prompt
+          end
+
+          # Configure the cog __not__ to append an initial prompt to the agent's system prompt when the agent is invoked
+          #
+          # #### See Also
+          # - `initial_prompt`
+          #
+          #: () -> void
+          def no_initial_prompt!
+            @values[:initial_prompt] = ""
+          end
+
+          # Get the validated, configured initial prompt that will be appended to the agent's system prompt when
+          # the agent is invoked
+          #
+          # Returns `nil` if __no__ prompt should be appended.
+          #
+          # #### See Also
+          # - `initial_prompt`
+          # - `no_initial_prompt!`
+          #
+          #: () -> String?
+          def valid_initial_prompt
+            @values[:initial_prompt].presence
+          end
+
+          # Configure the cog to apply the default set of system and user permissions when running the agent
+          #
+          # How these permissions are defined and configured is specific to the agent provider being used.
+          #
+          # The cog's default behaviour is to run with __no__ permissions.
+          #
+          # #### Alias Methods
+          # - `apply_permissions!`
+          # - `no_skip_permissions!`
+          #
+          # #### Inverse Methods
+          # - `no_apply_permissions!`
+          # - `skip_permissions!`
+          #
+          #: () -> void
+          def apply_permissions!
+            @values[:apply_permissions] = true
+          end
+
+          # Configure the cog to run the agent with __no__ permissions applied
+          #
+          # The cog's default behaviour is to run with __no__ permissions.
+          #
+          # #### Alias Methods
+          # - `no_apply_permissions!`
+          # - `skip_permissions!`
+          #
+          # #### Inverse Methods
+          # - `apply_permissions!`
+          # - `no_skip_permissions!`
+          #
+          #: () -> void
+          def no_apply_permissions!
+            @values[:apply_permissions] = false
+          end
+
+          # Check if the cog is configured to apply permissions when running the agent
+          #
+          # #### See Also
+          # - `apply_permissions!`
+          # - `no_apply_permissions!`
+          # - `skip_permissions!`
+          # - `no_skip_permissions!`
+          #
+          #: () -> bool
+          def apply_permissions?
+            !!@values[:apply_permissions]
+          end
+
+          # Configure the cog to display the prompt when running the agent
+          #
+          # Disabled by default.
+          #
+          # #### See Also
+          # - `no_show_prompt!`
+          # - `show_prompt?`
+          # - `display!`
+          #
+          #: () -> void
+          def show_prompt!
+            @values[:show_prompt] = true
+          end
+
+          # Configure the cog __not__ to display the prompt when running the agent
+          #
+          # This is the default behaviour.
+          #
+          # #### See Also
+          # - `show_prompt!`
+          # - `show_prompt?`
+          # - `no_display!`
+          # - `quiet!`
+          #
+          #: () -> void
+          def no_show_prompt!
+            @values[:show_prompt] = false
+          end
+
+          # Check if the cog is configured to display the prompt when running the agent
+          #
+          # #### See Also
+          # - `show_prompt!`
+          # - `no_show_prompt!`
+          #
+          #: () -> bool
+          def show_prompt?
+            @values.fetch(:show_prompt, false)
+          end
+
+          # Configure the cog to display the agent's in-progress messages when running
+          #
+          # This includes thinking blocks and other intermediate output from the agent.
+          # Enabled by default.
+          #
+          # #### See Also
+          # - `no_show_progress!`
+          # - `show_progress?`
+          # - `display!`
+          #
+          #: () -> void
+          def show_progress!
+            @values[:show_progress] = true
+          end
+
+          # Configure the cog __not__ to display the agent's in-progress messages when running
+          #
+          # This will hide thinking blocks and other intermediate output from the agent.
+          #
+          # #### See Also
+          # - `show_progress!`
+          # - `show_progress?`
+          # - `no_display!`
+          # - `quiet!`
+          #
+          #: () -> void
+          def no_show_progress!
+            @values[:show_progress] = false
+          end
+
+          # Check if the cog is configured to display the agent's in-progress messages when running
+          #
+          # #### See Also
+          # - `show_progress!`
+          # - `no_show_progress!`
+          #
+          #: () -> bool
+          def show_progress?
+            @values.fetch(:show_progress, true)
+          end
+
+          # Configure the cog to display the agent's final response
+          #
+          # Enabled by default.
+          #
+          # #### See Also
+          # - `no_show_response!`
+          # - `show_response?`
+          # - `display!`
+          #
+          #: () -> void
+          def show_response!
+            @values[:show_response] = true
+          end
+
+          # Configure the cog __not__ to display the agent's final response
+          #
+          # #### See Also
+          # - `show_response!`
+          # - `show_response?`
+          # - `no_display!`
+          # - `quiet!`
+          #
+          #: () -> void
+          def no_show_response!
+            @values[:show_response] = false
+          end
+
+          # Check if the cog is configured to display the agent's final response
+          #
+          # #### See Also
+          # - `show_response!`
+          # - `no_show_response!`
+          #
+          #: () -> bool
+          def show_response?
+            @values.fetch(:show_response, true)
+          end
+
+          # Configure the cog to display statistics about the agent's operation
+          #
+          # Enabled by default.
+          #
+          # #### See Also
+          # - `no_show_stats!`
+          # - `show_stats?`
+          # - `display!`
+          #
+          #: () -> void
+          def show_stats!
+            @values[:show_stats] = true
+          end
+
+          # Configure the cog __not__ to display statistics about the agent's operation
+          #
+          # #### See Also
+          # - `show_stats!`
+          # - `show_stats?`
+          # - `no_display!`
+          # - `quiet!`
+          #
+          #: () -> void
+          def no_show_stats!
+            @values[:show_stats] = false
+          end
+
+          # Check if the cog is configured to display statistics about the agent's operation
+          #
+          # #### See Also
+          # - `show_stats!`
+          # - `no_show_stats!`
+          #
+          #: () -> bool
+          def show_stats?
+            @values.fetch(:show_stats, true)
+          end
+
+          # Configure the cog to display all agent output
+          #
+          # This enables `show_prompt!`, `show_progress!`, `show_response!`, and `show_stats!`.
+          #
+          # #### See Also
+          # - `no_display!`
+          # - `quiet!`
+          # - `show_prompt!`
+          # - `show_progress!`
+          # - `show_response!`
+          # - `show_stats!`
+          #
+          #: () -> void
+          def display!
+            show_prompt!
+            show_progress!
+            show_response!
+            show_stats!
+          end
+
+          # Configure the cog to __hide__ all agent output
+          #
+          # This enables `no_show_prompt!`, `no_show_progress!`, `no_show_response!`, `no_show_stats!`.
+          #
+          # #### Alias Methods
+          # - `no_display!`
+          # - `quiet!`
+          #
+          # #### See Also
+          # - `display!`
+          # - `quiet!`
+          # - `no_show_prompt!`
+          # - `no_show_progress!`
+          # - `no_show_response!`
+          # - `no_show_stats!`
+          #
+          #: () -> void
+          def no_display!
+            no_show_prompt!
+            no_show_progress!
+            no_show_response!
+            no_show_stats!
+          end
+
+          # Check if the cog is configured to display any output while running
+          #
+          # #### See Also
+          # - `show_prompt?`
+          # - `show_progress?`
+          # - `show_response?`
+          # - `show_stats?`
+          #
+          #: () -> bool
+          def display?
+            show_prompt? || show_progress? || show_response? || show_stats?
+          end
+
+          # Configure the cog to dump raw messages received from the agent process to a file
+          #
+          # This is intended for development and debugging purposes to inspect the raw message stream
+          # from the agent provider.
+          #
+          #: (String) -> void
+          def dump_raw_agent_messages_to(filename)
+            @values[:dump_raw_agent_messages_to] = filename
+          end
+
+          # Get the validated, configured path to which raw agent messages should be dumped
+          #
+          # Returns `nil` if no path has been configured.
+          #
+          # This is intended for development and debugging purposes to inspect the raw message stream
+          # from the agent provider.
+          #
+          # #### See Also
+          # - `dump_raw_agent_messages_to`
+          #
+          #: () -> Pathname?
+          def valid_dump_raw_agent_messages_to_path
+            Pathname.new(@values[:dump_raw_agent_messages_to]) if @values[:dump_raw_agent_messages_to]
+          end
+
+          alias_method(:skip_permissions!, :no_apply_permissions!)
+          alias_method(:no_skip_permissions!, :apply_permissions!)
+          alias_method(:quiet!, :no_display!)
+        end
+      end
+    end
+  end
+end

data/lib/roast/dsl/cogs/agent/input.rb

@@ -0,0 +1,81 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module Cogs
+      class Agent < Cog
+        # Input specification for the agent cog
+        #
+        # The agent cog requires a prompt that will be sent to the agent for processing.
+        # Optionally, a session identifier can be provided to maintain context across multiple invocations.
+        class Input < Cog::Input
+          # The prompt to send to the agent for processing
+          #
+          #: String?
+          attr_accessor :prompt
+
+          # Optional session identifier for maintaining conversation context
+          #
+          # When provided, the agent will use this session to maintain context across
+          # multiple invocations, allowing for conversational interactions.
+          #
+          # The agent will fork a new session from this point, so multiple agents can resume from the
+          # same session state.
+          #
+          #: String?
+          attr_accessor :session
+
+          #: () -> void
+          def initialize
+            super
+            @prompt = nil #: String?
+          end
+
+          # Validate that the input has all required parameters
+          #
+          # This method ensures that a prompt has been provided before the agent executes.
+          #
+          # #### See Also
+          # - `coerce`
+          # - `valid_prompt!`
+          #
+          #: () -> void
+          def validate!
+            valid_prompt!
+          end
+
+          # Coerce the input from the return value of the input block
+          #
+          # If the input block returns a String, it will be used as the prompt value.
+          #
+          # #### See Also
+          # - `validate!`
+          #
+          #: (untyped) -> void
+          def coerce(input_return_value)
+            if input_return_value.is_a?(String)
+              self.prompt ||= input_return_value
+            end
+          end
+
+          # Get the validated prompt value
+          #
+          # Returns the prompt if it is present, otherwise raises an `InvalidInputError`.
+          #
+          # #### See Also
+          # - `prompt`
+          # - `validate!`
+          #
+          #: () -> String
+          def valid_prompt!
+            valid_prompt = @prompt
+            raise Cog::Input::InvalidInputError, "'prompt' is required" unless valid_prompt.present?
+
+            valid_prompt
+          end
+        end
+      end
+    end
+  end
+end

data/lib/roast/dsl/cogs/agent/output.rb

@@ -0,0 +1,59 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module Cogs
+      class Agent < Cog
+        # Output from running the agent cog
+        #
+        # Contains the agent's final response text, session identifier for conversation continuity,
+        # and statistics about the agent execution.
+        class Output < Cog::Output
+          include Cog::Output::WithJson
+          include Cog::Output::WithNumber
+          include Cog::Output::WithText
+
+          # The agent's final response text
+          #
+          # This is the text content of the agent's last message in the conversation.
+          # For multi-turn conversations, this represents only the final response, not the
+          # entire conversation history.
+          #
+          # #### See Also
+          # - `text` (from WithText module)
+          # - `lines` (from WithText module)
+          #
+          #: String
+          attr_reader :response
+
+          # The session identifier for this agent conversation
+          #
+          # This identifier can be used to resume the conversation in subsequent agent invocations.
+          # When provided to a new agent cog's input, the agent will have access to the full
+          # conversation history from this session.
+          #
+          # An agent resuming from this session will fork the session, so multiple agents can
+          # independently resume from the same initial session and each see the same state.
+          #
+          #: String
+          attr_reader :session
+
+          # Statistics about the agent execution
+          #
+          # Contains metrics such as execution duration, number of turns (back-and-forth exchanges
+          # with the agent), token usage, and per-model usage breakdown.
+          #
+          #: Stats
+          attr_reader :stats
+
+          private
+
+          def raw_text
+            response
+          end
+        end
+      end
+    end
+  end
+end

data/lib/roast/dsl/cogs/agent/provider.rb

@@ -0,0 +1,51 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module Cogs
+      class Agent < Cog
+        # Abstract base class for agent provider implementations
+        #
+        # Providers are responsible for interfacing with specific agent backends (e.g., Claude)
+        # to execute agent requests. Each provider must implement the `invoke` method to handle
+        # agent execution according to their specific API requirements.
+        #
+        # Subclasses should override `invoke` to provide concrete implementations that communicate
+        # with their respective agent services.
+        class Provider
+          # Initialize a new provider with the given configuration
+          #
+          # Stores the agent configuration for use during invocation. The configuration contains
+          # all settings needed to communicate with the agent service, such as API keys, model
+          # names, and execution parameters.
+          #
+          # #### See Also
+          # - `invoke`
+          #
+          #: (Config) -> void
+          def initialize(config)
+            super()
+            @config = config
+          end
+
+          # Execute an agent request and return the result
+          #
+          # This method must be implemented by subclasses to handle the actual agent execution.
+          # Implementations should use the stored configuration to set up the request, send the
+          # input to the agent service, and return a properly formatted output.
+          #
+          # Raises `NotImplementedError` if called on the base Provider class.
+          #
+          # #### See Also
+          # - `initialize`
+          #
+          #: (Input) -> Output
+          def invoke(input)
+            raise NotImplementedError, "Subclasses must implement #invoke"
+          end
+        end
+      end
+    end
+  end
+end