roast-ai 0.4.10 → 0.5.0

data/lib/roast/dsl/cogs/agent/providers/claude.rb

@@ -0,0 +1,31 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module Cogs
+      class Agent < Cog
+        module Providers
+          class Claude < Provider
+            class Output < Agent::Output
+              delegate :response, :session, :stats, to: :@invocation_result
+
+              #: (ClaudeInvocation::Result) -> void
+              def initialize(invocation_result)
+                super()
+                @invocation_result = invocation_result
+              end
+            end
+
+            #: (Agent::Input) -> Agent::Output
+            def invoke(input)
+              invocation = ClaudeInvocation.new(@config, input)
+              invocation.run!
+              Output.new(invocation.result)
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,92 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module Cogs
+      class Agent < Cog
+        # Statistics about agent execution
+        #
+        # Contains metrics tracking the performance and resource usage of an agent execution,
+        # including duration, conversation turns, token usage, and cost. Statistics are broken
+        # down by model when multiple models are used during execution.
+        class Stats
+          include ActiveSupport::NumberHelper
+
+          NO_VALUE = "---"
+
+          # The total execution duration in milliseconds
+          #
+          # Measures the wall-clock time from when the agent started executing until it completed.
+          # This includes all time spent on API calls, processing, and waiting.
+          #
+          #: Integer?
+          attr_accessor :duration_ms
+
+          # The number of conversation turns in the agent execution
+          #
+          # A turn represents one complete back-and-forth exchange between the user (or system)
+          # and the agent. For example, if the user sends a prompt and the agent responds, that
+          # is one turn. If the agent then uses a tool and responds again, that is another turn.
+          #
+          #: Integer?
+          attr_accessor :num_turns
+
+          # Aggregate token usage and cost across all models
+          #
+          # Provides the total input tokens, output tokens, and cost in USD for the entire
+          # agent execution, regardless of which models were used.
+          #
+          # #### See Also
+          # - `model_usage` - for per-model usage breakdown
+          # - `Agent::Usage`
+          #
+          #: Usage
+          attr_accessor :usage
+
+          # Token usage and cost broken down by model
+          #
+          # A hash mapping model names (as strings) to their individual usage statistics.
+          # This allows tracking how much each model contributed to the overall resource usage
+          # when multiple models were used during execution.
+          #
+          # #### See Also
+          # - `usage` - for aggregate usage across all models
+          # - `Agent::Usage`
+          #
+          #: Hash[String, Usage]
+          attr_accessor :model_usage
+
+          def initialize
+            @usage = Usage.new
+            @model_usage = {}
+          end
+
+          # Get a human-readable string representation of the statistics
+          #
+          # Formats the statistics into a multi-line string with the following information:
+          # - Number of turns
+          # - Total duration (formatted as a human-readable duration)
+          # - Total cost in USD (formatted with 6 decimal places)
+          # - Per-model token usage (input and output tokens)
+          #
+          # Values that are not available are shown as "---".
+          #
+          #: () -> String
+          def to_s
+            lines = []
+            lines << "Turns: #{num_turns.nil? ? NO_VALUE : number_to_human(num_turns)}"
+            lines << "Duration: #{duration_ms.nil? ? NO_VALUE : ActiveSupport::Duration.build((duration_ms || 0) / 1000).inspect}"
+            lines << "Cost (USD): $#{usage.cost_usd.nil? ? NO_VALUE : number_to_human(usage.cost_usd, precision: 6, significant: false)}"
+            model_usage.each do |m, u|
+              input_tokens = u.input_tokens.nil? ? NO_VALUE : number_to_human(u.input_tokens)
+              output_tokens = u.output_tokens.nil? ? NO_VALUE : number_to_human(u.output_tokens)
+              lines << "Tokens (#{m}): #{input_tokens} in, #{output_tokens} out"
+            end
+            lines.join("\n")
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module Cogs
+      class Agent < Cog
+        # Token usage and cost information for agent execution
+        #
+        # Tracks the number of input and output tokens consumed during agent execution,
+        # along with the associated cost in USD. This information is used to monitor
+        # resource consumption and estimate execution costs.
+        #
+        # Usage data can represent either aggregate usage across all models or usage
+        # for a specific model when tracked in the per-model breakdown.
+        #
+        # #### See Also
+        # - `Agent::Stats` - contains aggregate and per-model usage information
+        class Usage
+          # The number of input tokens consumed
+          #
+          # Input tokens represent the text sent to the agent, including the user prompt,
+          # system instructions, conversation history, and any other context provided to
+          # the model. This metric is used to calculate the cost of providing input to the agent.
+          #
+          # #### See Also
+          # - `output_tokens`
+          # - `cost_usd`
+          #
+          #: Integer?
+          attr_accessor :input_tokens
+
+          # The number of output tokens generated
+          #
+          # Output tokens represent the text generated by the agent in response to the input.
+          # This includes the agent's responses, reasoning, and any other text produced during
+          # execution. This metric is used to calculate the cost of the agent's output.
+          #
+          # #### See Also
+          # - `input_tokens`
+          # - `cost_usd`
+          #
+          #: Integer?
+          attr_accessor :output_tokens
+
+          # The total cost in United States Dollars (USD)
+          #
+          # Represents the monetary cost of the agent execution based on the provider's pricing
+          # model. This typically accounts for both input and output token usage, though pricing
+          # models may vary by provider and model.
+          #
+          # #### See Also
+          # - `input_tokens`
+          # - `output_tokens`
+          #
+          #: Float?
+          attr_accessor :cost_usd
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module DSL
+    module Cogs
+      # Agent cog for running coding agents on the local machine
+      #
+      # The agent cog runs a coding agent on the local machine with access to local files,
+      # tools, and MCP servers. It is designed for coding tasks and any work requiring local
+      # filesystem access.
+      #
+      # Key capabilities:
+      # - Access to local filesystem (read and write files)
+      # - Can run local tools and commands
+      # - Access to locally-configured MCP servers
+      # - Maintain session state across multiple invocations
+      # - Resume previous conversations using session identifiers
+      # - Track detailed execution statistics including token usage and cost
+      #
+      # For pure LLM interaction without local system access, use the `chat` cog instead.
+      class Agent < Cog
+        # Parent class for all agent cog errors
+        class AgentCogError < Roast::Error; end
+
+        # Raised when an unknown or unsupported provider is specified
+        class UnknownProviderError < AgentCogError; end
+
+        # Raised when a required provider is not configured
+        class MissingProviderError < AgentCogError; end
+
+        # Raised when a required prompt is not provided
+        class MissingPromptError < AgentCogError; end
+
+        # The configuration object for this agent cog instance
+        #
+        #: Agent::Config
+        attr_reader :config
+
+        # Execute the agent with the given input and return the output
+        #
+        # Invokes the configured agent provider with the input prompt and any session context.
+        # Optionally displays the user prompt, agent response, and execution statistics to the
+        # console based on the cog's configuration.
+        #
+        # The agent may make multiple turns (back-and-forth exchanges) during execution,
+        # especially when using tools. Each turn is counted in the execution statistics.
+        #
+        #: (Input) -> Output
+        def execute(input)
+          puts "[USER PROMPT] #{input.valid_prompt!}" if config.show_prompt?
+          output = provider.invoke(input)
+          # NOTE: If progress is displayed, the agent's response will always be the last progress message,
+          # so showing it again is duplicative.
+          puts "[AGENT RESPONSE] #{output.response}" if config.show_response? && !config.show_progress?
+          puts "[AGENT STATS] #{output.stats}" if config.show_stats?
+          puts "Session ID: #{output.session}" if config.show_stats?
+          output
+        end
+
+        private
+
+        #: () -> Provider
+        def provider
+          @provider ||= case config.valid_provider!
+          when :claude
+            Providers::Claude.new(config)
+          else
+            raise UnknownProviderError, "Unknown provider: #{config.valid_provider!}"
+          end
+        end
+      end
+    end
+  end
+end