roast-ai 1.0.2 → 1.2.0

data/examples/plugin-gem-example/Gemfile.lock

@@ -1,11 +1,12 @@
 PATH
   remote: ../..
   specs:
-    roast-ai (1.0.2)
+    roast-ai (1.2.0)
       activesupport (~> 8.0)
       async (>= 2.34)
       rainbow (>= 3.0.0)
-      ruby_llm (>= 1.8)
+      ruby_llm (>= 1.13)
+      type_toolkit (>= 0.0.5)
       zeitwerk (>= 2.6)
 
 PATH
@@ -17,7 +18,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (8.0.3)
+    activesupport (8.0.4.1)
       base64
       benchmark (>= 0.3)
       bigdecimal
@@ -26,7 +27,7 @@ GEM
       drb
       i18n (>= 1.6, < 2)
       logger (>= 1.4.2)
-      minitest (>= 5.1)
+      minitest (>= 5.1, < 6)
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
@@ -38,19 +39,19 @@ GEM
       metrics (~> 0.12)
       traces (~> 0.18)
     base64 (0.3.0)
-    benchmark (0.4.1)
-    bigdecimal (3.3.1)
-    concurrent-ruby (1.3.5)
-    connection_pool (2.5.4)
+    benchmark (0.5.0)
+    bigdecimal (4.1.2)
+    concurrent-ruby (1.3.7)
+    connection_pool (3.0.2)
     console (1.34.3)
       fiber-annotation
       fiber-local (~> 1.1)
       json
     date (3.4.1)
     drb (2.2.3)
-    erb (5.1.1)
+    erb (6.0.1.1)
     event_stream_parser (1.0.0)
-    faraday (2.14.1)
+    faraday (2.14.2)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
@@ -64,7 +65,7 @@ GEM
     fiber-local (1.1.0)
       fiber-storage
     fiber-storage (1.0.1)
-    i18n (1.14.7)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
     io-console (0.8.1)
     io-event (1.14.2)
@@ -72,7 +73,7 @@ GEM
       pp (>= 0.6.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.18.1)
+    json (2.19.5)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
     logger (1.7.0)
@@ -118,21 +119,24 @@ GEM
       parser (>= 3.3.7.2)
       prism (~> 1.4)
     ruby-progressbar (1.13.0)
-    ruby_llm (1.11.0)
+    ruby_llm (1.15.0)
       base64
       event_stream_parser (~> 1)
       faraday (>= 1.10.0)
       faraday-multipart (>= 1)
       faraday-net_http (>= 1)
       faraday-retry (>= 1)
-      marcel (~> 1.0)
-      ruby_llm-schema (~> 0.2.1)
+      marcel (~> 1)
+      ruby_llm-schema (~> 0)
       zeitwerk (~> 2)
     ruby_llm-schema (0.2.5)
     securerandom (0.4.1)
     stringio (3.1.7)
     traces (0.18.2)
     tsort (0.2.0)
+    type_toolkit (0.0.5)
+      lint_roller
+      rubocop (>= 1.72.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.2.0)

data/examples/simple_chat.rb

@@ -21,6 +21,6 @@ execute do
   # Ask a question with a template prompt. You can pass variables to it as you would an ERB template
   chat { template("examples/prompts/simple_prompt.md.erb", { lake_answer: chat!(:lake).response }) }
 
-  # Shorthand template syntax - searches prompts/ directory automatically
+  # Shorthand template syntax - searches prompts/ and templates/ directories automatically
   chat { template("simple_prompt", { lake_answer: chat!(:lake).response }) }
 end

data/examples/simple_pi_agent.rb

@@ -0,0 +1,18 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::Workflow
+
+config do
+  agent do
+    provider :pi
+    model "anthropic/claude-haiku-4-5-20251001"
+    append_system_prompt "Always respond in haiku form"
+    show_prompt!
+    dump_raw_agent_messages_to "tmp/pi-messages.log"
+  end
+end
+
+execute do
+  agent { "What is the world's largest lake?" }
+end

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/output.rb

@@ -241,8 +241,9 @@ module Roast
           lines.reverse.each do |line|
             # Look for numbers with various separators, formats, and currency symbols (very permissive)
             # Matches: 123, 1,234, 1_234, 1 234, 1.23, -1.23, 1.23e10, 1.23e-10
+            # Reversed so that the last number on the line is tried first (matching the bottom-up line order)
             matches = line.scan(/-?[\d\s$¢£€¥.,_]+(?:[eE][+-]?\d+)?/) #: as Array[String]
-            candidates.concat(matches.map(&:strip))
+            candidates.concat(matches.map(&:strip).reverse)
           end
 
           candidates.compact.uniq

data/lib/roast/cog/registry.rb

@@ -51,13 +51,13 @@ module Roast
       #
       #: (singleton(Roast::Cog)) -> void
       def use(cog_class)
-        reg = create_registration(cog_class)
-        cogs[reg.first] = reg.second
+        name, klass = create_registration(cog_class)
+        cogs[name] = klass
       end
 
       private
 
-      #: (singleton(Roast::Cog)) -> Array(Symbol, singleton(Cog))
+      #: (singleton(Roast::Cog)) -> [Symbol, singleton(Cog)]
       def create_registration(cog_class)
         cog_class_name = cog_class.name
         raise CouldNotDeriveCogNameError if cog_class_name.nil?

data/lib/roast/cog_input_manager.rb

@@ -159,7 +159,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 +175,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 +202,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,7 +5,7 @@ module Roast
   module Cogs
     class Agent < Cog
       class Config < Cog::Config
-        VALID_PROVIDERS = [:claude].freeze #: Array[Symbol]
+        VALID_PROVIDERS = [:claude, :pi].freeze #: Array[Symbol]
 
         # Configure the cog to use a specified provider when invoking an agent
         #
@@ -51,7 +51,7 @@ module Roast
         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(", ")}"
+            raise InvalidConfigError, "'#{provider}' is not a valid provider. Available providers include: #{VALID_PROVIDERS.join(", ")}"
           end
 
           provider

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

@@ -9,10 +9,14 @@ module Roast
       # 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
+        # The prompts to send to the agent for processing
         #
-        #: String?
-        attr_accessor :prompt
+        # When multiple prompts are specified, each subsequent prompt is passed to the agent as soon as it completes
+        # the previous one, in the same session throughout. This can be useful for helping to ensure the agent produces
+        # final outputs in the form you desire after performing a long and complex task.
+        #
+        #: Array[String]
+        attr_accessor :prompts
 
         # Optional session identifier for maintaining conversation context
         #
@@ -28,7 +32,7 @@ module Roast
         #: () -> void
         def initialize
           super
-          @prompt = nil #: String?
+          @prompts = [] #: Array[String]
         end
 
         # Validate that the input has all required parameters
@@ -37,41 +41,35 @@ module Roast
         #
         # #### See Also
         # - `coerce`
-        # - `valid_prompt!`
         #
         #: () -> void
         def validate!
-          valid_prompt!
+          raise Cog::Input::InvalidInputError, "At least one prompt is required" unless prompts.present?
+          raise Cog::Input::InvalidInputError, "Blank prompts are not allowed" if prompts.any?(&:blank?)
         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.
+        # If the input block returns an Array of Strings, the first will be used as the prompt and the
+        # rest will be used as finalizers.
         #
         # #### See Also
         # - `validate!`
         #
         #: (untyped) -> void
         def coerce(input_return_value)
-          if input_return_value.is_a?(String)
-            self.prompt ||= input_return_value
+          case input_return_value
+          when String
+            self.prompts = [input_return_value]
+          when Array
+            self.prompts = input_return_value.map(&:to_s)
           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
+        #: (String) -> void
+        def prompt=(prompt)
+          @prompts = [prompt]
         end
       end
     end