roast-ai 1.1.0 → 1.3.0

data/internal/documentation/{doc-comments.md → comments/doc-comments.md}

@@ -70,7 +70,8 @@ These files provide the primary interface between users and Roast. The documenta
 # 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.
+# If no provider is specified, Roast uses the provider named by the `ROAST_DEFAULT_AGENT_PROVIDER`
+# environment variable, or Pi (`:pi`) when that variable is unset.
 #
 # A provider must be properly installed on your system in order for Roast to be able to use it.
 #

data/internal/rubocop/cop/roast/no_test_class_nesting.rb

@@ -0,0 +1,126 @@
+# typed: false
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Roast
+      # Prevents nesting classes or modules inside reopened (non-test) class
+      # definitions in test files.
+      #
+      # When a class is reopened in a test file (e.g., `class Agent < Cog`) and
+      # contains nested class or module definitions, IDE test runners like
+      # RubyMine fail to discover test suites. Use `::` scoping instead.
+      #
+      # The cop walks the entire subtree of the offending class, so deeply
+      # nested structures (e.g., `class Agent < Cog; module Providers; ...`)
+      # are caught even when the nested definitions are not direct children.
+      #
+      # Classes nested inside test classes are exempt — helper stubs and
+      # fixtures defined inside a test suite are perfectly fine.
+      #
+      # @example Bad — reopened class with nested module
+      #   class Agent < Cog
+      #     module Providers
+      #       class Claude::MessageTest < ActiveSupport::TestCase
+      #         # ...
+      #       end
+      #     end
+      #   end
+      #
+      # @example Bad — reopened class with nested test class
+      #   class Agent < Cog
+      #     class ConfigTest < ActiveSupport::TestCase
+      #       # ...
+      #     end
+      #   end
+      #
+      # @example Good — :: scoping, no class reopening
+      #   module Agent::Providers
+      #     class Claude::MessageTest < ActiveSupport::TestCase
+      #       # ...
+      #     end
+      #   end
+      #
+      # @example Good — :: scoped test class
+      #   class Agent::ConfigTest < ActiveSupport::TestCase
+      #     # ...
+      #   end
+      #
+      # @example Good — helper class inside a test class
+      #   class Agent::OutputTest < ActiveSupport::TestCase
+      #     class FakeAdapter
+      #       def call; end
+      #     end
+      #   end
+      #
+      class NoTestClassNesting < Base
+        MSG = "Do not nest classes or modules inside reopened class `%<parent>s` in test files. " \
+          "Use `::` scoping instead (e.g., `class %<parent>s::Nested` or `module %<parent>s::Nested`)."
+
+        # @!method test_base_class?(node)
+        def_node_matcher :test_base_class?, <<~PATTERN
+          {
+            (const (const {nil? cbase} :ActiveSupport) :TestCase)
+            (const (const {nil? cbase} :Minitest) :Test)
+            (const {nil? cbase} :Minitest)
+          }
+        PATTERN
+
+        def on_class(node)
+          # Test classes are allowed to contain nested definitions (helpers, stubs)
+          return if test_class?(node)
+
+          # Classes nested inside a test class are helpers — leave them alone
+          return if inside_test_class?(node)
+
+          # Flag if this non-test class contains any nested class or module
+          return unless contains_nested_definitions?(node)
+
+          message = format(MSG, parent: node.identifier.const_name)
+          add_offense(node.loc.keyword.join(node.identifier.source_range), message: message)
+        end
+
+        private
+
+        def test_class?(node)
+          node.parent_class && test_base_class?(node.parent_class)
+        end
+
+        # Returns true if any ancestor of +node+ is a test class.
+        def inside_test_class?(node)
+          current = node.parent
+          while current
+            return true if current.class_type? && test_class?(current)
+
+            current = current.parent
+          end
+          false
+        end
+
+        # Returns true if +node+ contains any nested class or module definition
+        # at any depth, excluding those sheltered inside an intermediate test class.
+        def contains_nested_definitions?(node)
+          node.each_descendant(:class, :module) do |descendant|
+            next if sheltered_by_test_class?(descendant, node)
+
+            return true
+          end
+          false
+        end
+
+        # Returns true if there is a test class between +descendant+ and +stop_at+
+        # in the ancestor chain — meaning the descendant is a helper inside a test
+        # class and should not count as a problematic nested definition.
+        def sheltered_by_test_class?(descendant, stop_at)
+          current = descendant.parent
+          while current && current != stop_at
+            return true if current.class_type? && test_class?(current)
+
+            current = current.parent
+          end
+          false
+        end
+      end
+    end
+  end
+end

data/internal/rubocop/rubocop-roast.yml

@@ -0,0 +1,6 @@
+Roast/NoTestClassNesting:
+  Description: "Prevents nesting test classes inside reopened production classes. Use :: scoping instead."
+  Enabled: true
+  VersionAdded: "0.1.0"
+  Include:
+    - "test/**/*.rb"

data/internal/workflows/maintenance/branch_docs_impact.rb

@@ -0,0 +1,97 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::Workflow
+
+# Gets the committed diff of the current branch vs origin/main, then analyzes it for potential
+# documentation impacts, and optionally applies fixes. This is meant to be run as a pre-merge check, to
+# catch any potential documentation issues before they get merged into main.
+#
+# Accepts a `--fix` flag to apply any suggested fixes in place. Otherwise, it just reports the analysis
+# and recommended fixes without applying them.
+
+config do
+  agent do
+    provider :claude
+    model "claude-opus-4-7"
+    quiet!
+  end
+  chat do
+    provider :openai
+    model "gpt-5"
+    quiet!
+  end
+end
+
+execute do
+  cmd(:diff) do
+    merge_base = %x(git merge-base origin/main HEAD).strip
+    fail!("could not determine merge-base with origin/main — run `git fetch origin main` first") if merge_base.empty?
+    "git diff #{merge_base} HEAD"
+  end
+
+  agent(:analyzer) do
+    skip! if cmd!(:diff).text.strip.empty?
+    fail!("diff too large (#{cmd!(:diff).text.bytesize} bytes) to analyze — narrow the branch or exclude generated files") if cmd!(:diff).text.bytesize > 500_000
+    <<~PROMPT
+      You are checking whether a git diff makes any existing documentation stale.
+
+      Rules:
+      - Use ONLY the diff below. Do not run any commands.
+      - Be thorough about finding real issues — do not be conservative.
+      - But do NOT speculate about docs you cannot see in the diff.
+      - No markdown headers, no preamble, no caveats, no "limitations" sections.
+
+      Output format — pick exactly one:
+
+      If nothing in the diff affects existing docs, output a single line:
+        No documentation impact.
+
+      Otherwise, output one block per affected doc, separated by blank lines:
+        <doc/path.md>
+        Stale because: <one sentence>
+        Fix: <one sentence>
+
+      --- DIFF START ---
+      #{cmd!(:diff).text}
+      --- DIFF END ---
+    PROMPT
+  end
+
+  chat(:report) do
+    skip! if cmd!(:diff).text.strip.empty?
+    <<~PROMPT
+      Based on the following analysis, summarize the impact of the changes in this branch on the project's documentation.
+      Highlight any significant improvements or regressions, and provide recommendations for any additional documentation updates that may be necessary.
+      Do not suggest updates that are not needed.
+      Do not be verbose. Be super concise.
+
+      Analysis:
+      #{agent!(:analyzer).response}
+    PROMPT
+  end
+
+  agent(:fixer) do
+    skip! unless arg?(:fix)
+    skip! if cmd!(:diff).text.strip.empty?
+    skip! if agent!(:analyzer).response.strip == "No documentation impact."
+    <<~PROMPT
+      Apply the documentation fixes suggested in the analysis below. Edit the
+      affected files in place. Do not modify any code files; docs only.
+
+      #{agent!(:analyzer).response}
+    PROMPT
+  end
+
+  ruby(:output) do
+    if cmd!(:diff).text.strip.empty?
+      puts "No changes vs origin/main — nothing to analyze."
+    else
+      files = cmd!(:diff).out.scan(%r{^diff --git a/.+ b/(.+)$}).flatten
+      puts "Files considered (#{files.size}):"
+      files.each { |f| puts "  #{f}" }
+      puts "ANALYSIS:\n#{chat!(:report).response}"
+      puts(agent?(:fixer) ? "Fixes applied." : "(Next time, run with `-- fix` to auto-apply suggested edits)")
+    end
+  end
+end

data/internal/workflows/maintenance/deprecated_models_docs_updater.rb

@@ -0,0 +1,78 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::Workflow
+
+# Looks at the Anthropic (https://platform.claude.com/docs/en/about-claude/model-deprecations) and
+# OpenAI (https://developers.openai.com/api/docs/deprecations) model-deprecation pages and updates all
+# docs, doc comments and code references to deprecated/retired models to reflect those changes. This is
+# meant to be run periodically to keep all the references to models up to date.
+
+config do
+  agent do
+    provider :claude
+    model "claude-opus-4-8"
+    quiet!
+  end
+end
+
+execute do
+  agent(:model_verifier) do
+    <<~PROMPT
+      Check both of these pages for deprecated/retired models and their suggested replacements:
+      - Anthropic (Claude): https://platform.claude.com/docs/en/about-claude/model-deprecations
+      - OpenAI: https://developers.openai.com/api/docs/deprecations
+
+      Include every deprecated or retired model that has a recommended replacement, from both pages.
+      Only include models — ignore deprecated API endpoints, tools, or other non-model features.
+
+      Output ONLY a JSON object of exactly this shape, with no surrounding prose:
+      {"outdated": [{"model": "<outdated_model>", "replacement": "<replacement_model>"}]}
+
+      If there are none, output {"outdated": []}.
+    PROMPT
+  end
+
+  agent(:model_finder) do
+    <<~PROMPT
+      You are a code search engine. Search through the codebase and documentation for any references to
+      the outdated models below, including test files, and list every place where they are mentioned.
+
+      The input is a JSON object of the form:
+      {"outdated": [{"model": "<outdated_model>", "replacement": "<replacement_model>"}]}
+
+      INPUT:
+      #{agent!(:model_verifier).response}
+
+      Output ONLY a JSON object of exactly this shape, with no surrounding prose, carrying the
+      replacement through for each model you find a reference to:
+      {"references": [{"model": "<outdated_model>", "replacement": "<replacement_model>", "locations": ["<file_path>:<line_number>"]}]}
+
+      If you find no references, output {"references": []}.
+    PROMPT
+  end
+
+  agent(:updater) do |my|
+    finder = agent!(:model_finder)
+    skip! if finder.json![:references].blank?
+    my.session = finder.session
+    <<~PROMPT
+      For each reference you found of an outdated model, update the reference to use the suggested replacement model instead. Make sure to update all types of references, including documentation, doc comments and code references. Output the list of updated references in the following format:
+      <outdated_model_1> -> <replacement_model_1>:
+      - <file_path>:<line_number>
+      <outdated_model_2> -> <replacement_model_2>:
+      - <file_path>:<line_number>
+      ...
+    PROMPT
+  end
+
+  ruby(:output) do
+    if agent?(:updater)
+      puts "[OUTDATED MODELS & REPLACEMENTS]\n #{agent!(:model_verifier).response}"
+      puts "[REFERENCES IN CODEBASE]\n #{agent!(:model_finder).response}"
+      puts "[UPDATED REFERENCES]\n #{agent!(:updater).response}"
+    else
+      puts "No references to outdated models found — nothing to update."
+    end
+  end
+end

data/lib/roast/cog/config.rb

@@ -230,7 +230,7 @@ module Roast
       #
       #: () -> bool
       def abort_on_failure?
-        !!@values[:abort_on_failure]
+        @values.fetch(:abort_on_failure, true)
       end
 
       # Configure the cog to run external commands in the specified working directory

data/lib/roast/cog_input_manager.rb

@@ -4,6 +4,8 @@
 module Roast
   # Context in which an individual cog block within the `execute` block of a workflow is evaluated
   class CogInputManager
+    include WorkflowParamAccessors
+
     class CogOutputAccessError < Roast::Error; end
 
     class CogDoesNotExistError < CogOutputAccessError; end
@@ -104,50 +106,6 @@ module Roast
       end
     end
 
-    #: () -> String
-    def target!
-      raise ArgumentError, "expected exactly one target" unless @workflow_context.params.targets.length == 1
-
-      @workflow_context.params.targets.first #: as String
-    end
-
-    #: () -> Array[String]
-    def targets
-      @workflow_context.params.targets.dup
-    end
-
-    #: (Symbol) -> bool
-    def arg?(value)
-      @workflow_context.params.args.include?(value)
-    end
-
-    #: () -> Array[Symbol]
-    def args
-      @workflow_context.params.args.dup
-    end
-
-    #: (Symbol) -> String?
-    def kwarg(key)
-      @workflow_context.params.kwargs[key]
-    end
-
-    #: (Symbol) -> String
-    def kwarg!(key)
-      raise ArgumentError, "expected keyword argument '#{key}' to be present" unless @workflow_context.params.kwargs.include?(key)
-
-      @workflow_context.params.kwargs[key] #: as String
-    end
-
-    #: (Symbol) -> bool
-    def kwarg?(key)
-      @workflow_context.params.kwargs.include?(key)
-    end
-
-    #: () -> Hash[Symbol, String]
-    def kwargs
-      @workflow_context.params.kwargs.dup
-    end
-
     #: () -> Pathname
     def tmpdir
       Pathname.new(@workflow_context.tmpdir).realpath
@@ -159,7 +117,7 @@ module Roast
     # Supports both relative shorthand paths like "greeting" and full absolute paths.
     #
     # @param path [String, Pathname] The template path to resolve. Can be:
-    #   - Shorthand name: "greeting" -> searches for prompts/greeting.md.erb
+    #   - Shorthand name: "greeting" -> searches for prompts/greeting.md.erb or templates/greeting.md.erb
     #   - With extension: "template.erb" -> searches for template.erb
     #   - Absolute path: "/full/path/to/template.erb" -> uses as-is
     # @param args [Hash] Template variables for ERB interpolation
@@ -175,13 +133,14 @@ module Roast
     # 1. Absolute path as-is (if absolute)
     # 2-4. Workflow directory: path, path.erb, path.md.erb
     # 5-7. Workflow directory prompts/: prompts/path, prompts/path.erb, prompts/path.md.erb
-    # 8-10. Current directory: path, path.erb, path.md.erb
-    # 11-13. Current directory prompts/: prompts/path, prompts/path.erb, prompts/path.md.erb
+    # 8-10. Workflow directory templates/: templates/path, templates/path.erb, templates/path.md.erb
+    # 11-13. Current directory: path, path.erb, path.md.erb
+    # 14-16. Current directory prompts/: prompts/path, prompts/path.erb, prompts/path.md.erb
+    # 17-19. Current directory templates/: templates/path, templates/path.erb, templates/path.md.erb
+    # 20-22. Tilde-expanded path: path, path.erb, path.md.erb
     #
     #: (String | Pathname, ?Hash) -> String
     def template(path, args = {})
-      # NOTE: Pathname does not expand ~ for home directory automatically.
-      # This is tracked in issue https://github.com/Shopify/roast/issues/663.
       path = Pathname.new(path) unless path.is_a?(Pathname)
 
       # Priority stack of places to look for a matching file
@@ -201,17 +160,37 @@ module Roast
       candidate_paths << workflow_dir / "prompts" / "#{path}.erb"
       candidate_paths << workflow_dir / "prompts" / "#{path}.md.erb"
 
-      # 8-10. Relative to current working directory
+      # 8-10. Relative to workflow directory templates folder
+      candidate_paths << workflow_dir / "templates" / path
+      candidate_paths << workflow_dir / "templates" / "#{path}.erb"
+      candidate_paths << workflow_dir / "templates" / "#{path}.md.erb"
+
+      # 11-13. Relative to current working directory
       pwd = Pathname.pwd
       candidate_paths << pwd / path
       candidate_paths << pwd / "#{path}.erb"
       candidate_paths << pwd / "#{path}.md.erb"
 
-      # 11-13. Relative to current working directory prompts folder
+      # 14-16. Relative to current working directory prompts folder
       candidate_paths << pwd / "prompts" / path
       candidate_paths << pwd / "prompts" / "#{path}.erb"
       candidate_paths << pwd / "prompts" / "#{path}.md.erb"
 
+      # 17-19. Relative to current working directory templates folder
+      candidate_paths << pwd / "templates" / path
+      candidate_paths << pwd / "templates" / "#{path}.erb"
+      candidate_paths << pwd / "templates" / "#{path}.md.erb"
+
+      # 20-22. Tilde expanded path
+      begin
+        expanded_path = Pathname.new(File.expand_path(path))
+        candidate_paths << expanded_path
+        candidate_paths << Pathname.new(File.expand_path("#{expanded_path}.erb"))
+        candidate_paths << Pathname.new(File.expand_path("#{expanded_path}.md.erb"))
+      rescue ArgumentError
+        # File.expand_path raises when expanding ~something/foo (assuming "something" is not a real user).
+        # Nothing to do here, falls back to other candidate paths without tilde expansion.
+      end
       # Use the first path that exists
       resolved_path = candidate_paths.find(&:exist?)
 

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

@@ -5,12 +5,21 @@ module Roast
   module Cogs
     class Agent < Cog
       class Config < Cog::Config
-        VALID_PROVIDERS = [:claude, :pi].freeze #: Array[Symbol]
+        VALID_PROVIDERS = [:pi, :claude].freeze #: Array[Symbol]
+
+        # Environment variable that overrides the built-in default agent provider.
+        #
+        # When an agent cog does not explicitly configure a provider, Roast uses the provider named by
+        # this variable, falling back to the built-in default (`VALID_PROVIDERS.first`, i.e. `:pi`) when it
+        # is unset or blank. The value is normalized (surrounding whitespace stripped, then downcased)
+        # before lookup, and an explicit `provider` configured on the cog always takes precedence over it.
+        DEFAULT_PROVIDER_ENV_VAR = "ROAST_DEFAULT_AGENT_PROVIDER" #: String
 
         # 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.
+        # If no provider is specified, Roast uses the provider named by the `ROAST_DEFAULT_AGENT_PROVIDER`
+        # environment variable, or Pi (`:pi`) when that variable is unset.
         #
         # A provider must be properly installed on your system in order for Roast to be able to use it.
         #
@@ -24,7 +33,8 @@ module Roast
 
         # Configure the cog to use the default provider when invoking an agent
         #
-        # The default provider used by Roast is Anthropic Claude Code (`:claude`).
+        # The default provider is the one named by the `ROAST_DEFAULT_AGENT_PROVIDER` environment variable,
+        # or Pi (`:pi`) when that variable is unset.
         #
         # The provider must be properly installed on your system in order for Roast to be able to use it.
         #
@@ -38,6 +48,10 @@ module Roast
 
         # Get the validated provider name that the cog is configured to use when invoking an agent
         #
+        # The provider is resolved in order of precedence: the provider explicitly configured on the cog,
+        # then the `ROAST_DEFAULT_AGENT_PROVIDER` environment variable (normalized by stripping surrounding
+        # whitespace and downcasing), then the built-in default (`VALID_PROVIDERS.first`, i.e. `:pi`).
+        #
         # 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
@@ -49,9 +63,10 @@ module Roast
         #
         #: () -> Symbol
         def valid_provider!
-          provider = @values[:provider] || VALID_PROVIDERS.first
+          env_default = ENV[DEFAULT_PROVIDER_ENV_VAR].presence&.strip&.downcase&.to_sym
+          provider = @values[:provider] || env_default || VALID_PROVIDERS.first
           unless VALID_PROVIDERS.include?(provider)
-            raise ArgumentError, "'#{provider}' is not a valid provider. Available providers include: #{VALID_PROVIDERS.join(", ")}"
+            raise InvalidConfigError, "'#{provider}' is not a valid provider. Available providers include: #{VALID_PROVIDERS.join(", ")}"
           end
 
           provider
@@ -131,6 +146,47 @@ module Roast
           @values[:model].presence
         end
 
+        # Configure the cog to stop the agent if it runs longer than the given number of seconds
+        #
+        # When the limit is reached, the agent process is killed and the cog raises
+        # `Roast::CommandRunner::TimeoutError`. By default there is no timeout.
+        #
+        # #### See Also
+        # - `no_timeout!`
+        #
+        #: (Integer) -> void
+        def timeout(seconds)
+          @values[:timeout] = seconds
+        end
+
+        # Configure the cog to let the agent run for as long as it takes (the default)
+        #
+        # #### See Also
+        # - `timeout`
+        #
+        #: () -> void
+        def no_timeout!
+          @values[:timeout] = nil
+        end
+
+        # Get the validated number of seconds the agent may run before it is stopped
+        #
+        # Returns `nil` if the agent has no timeout. Raises an `InvalidConfigError` if the configured
+        # timeout is not positive.
+        #
+        # #### See Also
+        # - `timeout`
+        # - `no_timeout!`
+        #
+        #: () -> Integer?
+        def valid_timeout
+          seconds = @values[:timeout]
+          return if seconds.nil?
+          return seconds if seconds.positive?
+
+          raise InvalidConfigError, "timeout must be a positive number of seconds, got #{seconds.inspect}"
+        end
+
         # Configure the cog with a custom system prompt that will completely replace the agent's
         # default system prompt every time the agent is invoked
         #

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

@@ -56,11 +56,14 @@ module Roast
             #: (Agent::Config, String, String?, ?fork_session: bool) -> void
             def initialize(config, prompt, session, fork_session: true)
               @base_command = config.valid_command #: (String | Array[String])?
-              @model = config.valid_model #: String?
+              # The Claude CLI expects a bare model name, while Pi expects a fully-qualified
+              # `anthropic/<model>` id. Strip the prefix so the same model string works for either provider.
+              @model = config.valid_model&.delete_prefix("anthropic/") #: String?
               @append_system_prompt = config.valid_append_system_prompt #: String?
               @replace_system_prompt = config.valid_replace_system_prompt #: String?
               @apply_permissions = config.apply_permissions? #: bool
               @working_directory = config.valid_working_directory #: Pathname?
+              @timeout = config.valid_timeout #: Integer?
               @context = Context.new #: Context
               @result = Result.new #: Result
               @raw_dump_file = config.valid_dump_raw_agent_messages_to_path #: Pathname?
@@ -77,17 +80,18 @@ module Roast
               raise ClaudeAlreadyStartedError if started?
 
               @started = true
-              puts "[USER PROMPT] #{@prompt}" if @show_prompt
+              Event << { block: { header: "USER PROMPT", content: @prompt } } if @show_prompt
               _stdout, stderr, status = CommandRunner.execute(
                 command_line,
                 working_directory: @working_directory,
                 stdin_content: @prompt,
+                timeout: @timeout,
                 stdout_handler: lambda { |line| handle_stdout(line) },
               )
 
               if status.success?
                 @completed = true
-                puts "[AGENT RESPONSE] #{@result.response}" if @show_response
+                Event << { block: { header: "AGENT RESPONSE", content: @result.response } } if @show_response
               else
                 @failed = true
                 @result.success = false

data/lib/roast/cogs/agent/providers/claude/messages/result_message.rb

@@ -31,7 +31,7 @@ module Roast
                 @content = hash.delete(:result) || ""
                 @success = hash.delete(:success) || subtype == "success"
                 if hash.delete(:is_error) || subtype == "error"
-                  @content = @content || hash.dig(:error, :message) || "Unknown error"
+                  @content = @content.presence || hash.dig(:error, :message) || "Unknown error"
                   hash.delete(:error)
                 end