roast-ai 0.4.0 → 0.4.1

data/examples/agent_continue/explore_api/prompt.md

@@ -0,0 +1,6 @@
+Explore the GitHub API and document:
+- Key endpoints for repository management
+- Authentication requirements
+- Rate limiting considerations
+
+Format as a structured summary.

data/examples/agent_continue/implement_client/prompt.md

@@ -0,0 +1,6 @@
+Create a Ruby client for the GitHub API that includes:
+- Basic authentication
+- Repository listing
+- Repository creation
+
+Use the information from the API exploration.

data/examples/agent_continue/inline_workflow.yml

@@ -0,0 +1,20 @@
+description: Example workflow using inline agent prompts with continuation
+
+# This example demonstrates using inline agent prompts (direct text after ^)
+# combined with the new parameters
+
+steps:
+  # Start with a fresh context
+  - ^Create a simple Ruby class for managing a todo list with add, remove, and list methods
+  
+  # Continue from previous session to add more features
+  - ^continue_adding_features
+  
+  # Use context summary to understand what was built
+  - ^document_with_context
+
+continue_adding_features:
+  continue: true  # This continues from the previous agent session
+
+document_with_context:
+  include_context_summary: true  # This will include context about previous steps

data/examples/agent_continue/refactor_code/prompt.md

@@ -0,0 +1,2 @@
+Now implement the refactoring suggestions you identified.
+Start with the highest priority items.

data/examples/agent_continue/verify_changes/prompt.md

@@ -0,0 +1,6 @@
+Review all the changes made by the coding agent steps.
+Provide a summary of:
+- What was analyzed
+- What refactorings were applied
+- What documentation was added
+- Any potential issues or concerns

data/examples/agent_continue/workflow.yml

@@ -0,0 +1,27 @@
+description: Example workflow demonstrating agent continuation and context summary features
+
+# This example shows how to use the new coding agent parameters:
+# - continue: true - continues from previous agent session
+# - include_context_summary: true - includes workflow context in the prompt
+
+target: "**/*.rb"
+
+steps:
+  # First agent step - starts fresh
+  - ^analyze_codebase
+  
+  # Second agent step - continues from previous session
+  - ^refactor_code
+  
+  # Third agent step - includes context summary from previous steps
+  - ^add_documentation
+  
+  # Final verification step
+  - verify_changes
+
+# Step configurations
+refactor_code:
+  continue: true  # Continue from the previous agent session
+
+add_documentation:
+  include_context_summary: true  # Include workflow context in the prompt

data/examples/apply_diff_demo/README.md

@@ -0,0 +1,58 @@
+# Apply Diff Demo
+
+This example demonstrates the `apply_diff` tool, which shows users a colored diff of proposed changes and applies them only after user confirmation.
+
+## What this workflow does
+
+1. **Creates a sample file** - Generates `hello.txt` with simple text content
+2. **Applies a simple change** - Uses `apply_diff` to modify the greeting and ask for user confirmation
+
+## Key features demonstrated
+
+- **Interactive approval** - The `apply_diff` tool shows a clear, colored diff and waits for user confirmation
+- **Safe modifications** - Changes are only applied when the user explicitly approves them
+- **Colored visualization** - Diff format shows exactly what will be changed with:
+  - **Red** lines starting with `-` for removed content
+  - **Green** lines starting with `+` for added content  
+  - **Cyan** line numbers and context (`@@` lines)
+  - **Bold** diff headers
+- **Optional descriptions** - You can provide context about why a change is being made
+
+## Running the workflow
+
+```bash
+bin/roast examples/apply_diff_demo/workflow.yml
+```
+
+## Expected interaction
+
+When you run this workflow, you'll see:
+
+1. The workflow creates a simple `hello.txt` file
+2. It proposes changing "Hello World!" to "Hello, Apply Diff Demo!"
+3. It shows you a colored diff of the proposed change:
+   ```
+   📝 Proposed change for hello.txt:
+   Description: Update greeting to be more specific to the demo
+   
+   diff --git a/hello.txt b/hello.txt
+   index 1234567..abcdefg 100644
+   --- a/hello.txt
+   +++ b/hello.txt
+   @@ -1,3 +1,3 @@
+   -Hello World!
+   +Hello, Apply Diff Demo!
+    This is a demo file.
+    We will modify this file in the next step.
+   ```
+4. It asks for your confirmation: `Apply this change? (y/n)`
+5. If you say "y", it applies the change; if "n", it cancels
+6. Finally, it reads the file again to show the result
+
+## Tools used
+
+- `Roast::Tools::WriteFile` - Creates the initial sample file
+- `Roast::Tools::ReadFile` - Reads files to show results
+- `Roast::Tools::ApplyDiff` - Shows colored diffs and applies changes with user confirmation
+
+This pattern is useful for any workflow where you want to make targeted changes to files but give users control over what actually gets applied.

data/examples/apply_diff_demo/apply_simple_change/prompt.md

@@ -0,0 +1,13 @@
+# Apply Simple Change
+
+Now use the apply_diff function to modify the `hello.txt` file. Let's change the greeting from "Hello World!" to "Hello, Apply Diff Demo!".
+
+Use the apply_diff function with:
+- `file_path`: "hello.txt"
+- `old_content`: "Hello World!"
+- `new_content`: "Hello, Apply Diff Demo!"
+- `description`: "Update greeting to be more specific to the demo"
+
+This will show the user a colored diff of the proposed change and ask for their confirmation before applying it.
+
+After the change is applied (or declined), read the file again to show the final result.

data/examples/apply_diff_demo/create_sample_file/prompt.md

@@ -0,0 +1,11 @@
+# Create Sample File
+
+Create a simple text file called `hello.txt` with the following content:
+
+```
+Hello World!
+This is a demo file.
+We will modify this file in the next step.
+```
+
+Use the write_file function to create this file.

data/examples/apply_diff_demo/workflow.yml

@@ -0,0 +1,24 @@
+# Apply Diff Demo
+#
+# This workflow demonstrates the apply_diff tool which shows users a diff
+# and applies changes based on their confirmation. It's useful for making
+# targeted changes to files with user approval.
+
+name: Apply Diff Demo
+model: gpt-4o-mini
+
+tools:
+  - Roast::Tools::WriteFile
+  - Roast::Tools::ReadFile
+  - Roast::Tools::ApplyDiff
+
+steps:
+  - create_sample_file
+  - apply_simple_change
+
+# Step configurations
+create_sample_file:
+  print_response: false
+
+apply_simple_change:
+  print_response: true

data/examples/context_management_demo/README.md

@@ -0,0 +1,43 @@
+# Context Management Demo
+
+This example demonstrates Roast's automatic context management feature, which helps prevent workflow failures when conversation history exceeds the LLM's context window.
+
+## Features Demonstrated
+
+1. **Automatic Token Tracking**: Monitors token usage throughout workflow execution
+2. **Configurable Thresholds**: Set when to trigger warnings or compaction
+3. **Context Preservation**: Specify critical steps to retain during compaction
+
+## Configuration
+
+```yaml
+context_management:
+  enabled: true          # Enable context management
+  strategy: auto         # Compaction strategy (auto, summarize, prune, none)
+  threshold: 0.8         # Trigger at 80% of context window
+  max_tokens: 10000      # Override default limit (for demo purposes)
+  retain_steps:          # Steps to always keep in full
+    - analyze_requirements
+    - generate_summary
+```
+
+## Running the Demo
+
+```bash
+roast execute context_management_demo
+```
+
+The workflow intentionally generates verbose responses to demonstrate how context management handles large amounts of text without failing.
+
+## What to Observe
+
+1. **Token Usage Warnings**: Watch for warnings as the context approaches limits
+2. **Automatic Handling**: The workflow continues even with large outputs
+3. **Preserved Context**: Critical steps remain accessible throughout execution
+
+## Customization
+
+Try modifying the configuration:
+- Lower `max_tokens` to trigger compaction sooner
+- Change `strategy` to test different compaction approaches
+- Add more steps to `retain_steps` to preserve additional context

data/examples/context_management_demo/workflow.yml

@@ -0,0 +1,42 @@
+name: Context Management Demo
+tools:
+  - Roast::Tools::ReadFile
+  - Roast::Tools::WriteFile
+
+# Context management configuration
+context_management:
+  enabled: true
+  strategy: auto
+  threshold: 0.8  # Trigger compaction at 80% of context window
+  max_tokens: 10000  # Demo with smaller limit for testing
+  retain_steps:
+    - analyze_requirements
+    - generate_summary
+
+steps:
+  - analyze_requirements: |
+      Analyze this text and list the key requirements:
+      
+      We need a system that can:
+      1. Process customer orders
+      2. Track inventory levels
+      3. Generate reports
+      4. Handle refunds
+      5. Integrate with payment systems
+      
+  - expand_details: |
+      For each requirement from the previous step, provide detailed implementation notes,
+      technical considerations, and potential challenges. Be very thorough and verbose
+      to help test the context management system.
+      
+  - generate_more_context: |
+      Now describe the database schema needed for this system. Include all tables,
+      relationships, indexes, and data types. Be extremely detailed.
+      
+  - add_api_design: |
+      Design a complete REST API for this system. Include all endpoints, request/response
+      formats, authentication, and error handling. Provide examples for each endpoint.
+      
+  - generate_summary: |
+      Create a concise executive summary of the system design. Focus on the key decisions
+      and trade-offs made during the design process.

data/examples/interpolation/workflow.yml

@@ -1,5 +1,5 @@
 name: interpolation_example
-model: anthropic:claude-3-7-sonnet
+model: gpt-4o-mini
 
 tools:
   - Roast::Tools::ReadFile

data/examples/no_model_fallback/README.md

@@ -0,0 +1,17 @@
+# No Model Fallback Example
+
+This example demonstrates the issue where workflows without explicit model specification do not properly fall back to a default model.
+
+## Purpose
+
+This workflow is based on the interpolation example but intentionally omits the `model` field to test the fallback behavior.
+
+## Expected Behavior
+
+The workflow should fall back to a default model when no model is specified at the workflow level.
+
+## Usage
+
+```bash
+bin/roast examples/no_model_fallback/workflow.yml --file examples/no_model_fallback/sample.rb
+```

data/examples/no_model_fallback/analyze_file/prompt.md

@@ -0,0 +1 @@
+Analyze the file at: <%= workflow.file %>

data/examples/no_model_fallback/analyze_patterns/prompt.md

@@ -0,0 +1,27 @@
+Extract some patterns about this file and return in json format like this:
+
+<json>
+{
+  "code_patterns": {
+    "class_structure": {
+      "name": "Calculator",
+      "instance_variables": ["@memory"],
+      "method_count": 7,
+      "method_types": {
+        "constructor": ["initialize"],
+        "operations": ["add", "subtract", "multiply", "divide"],
+        "accessors": ["memory"],
+        "utility": ["clear"]
+      }
+    },
+    "error_handling": {
+      "techniques": ["conditional raise", "zero check"],
+      "examples": ["raise \"Division by zero!\" if number.zero?"]
+    },
+    "design_patterns": {
+      "state": "Uses instance variable to maintain calculator state",
+      "command": "Each operation method modifies the internal state"
+    }
+  }
+}
+</json>

data/examples/no_model_fallback/generate_report_for_md/prompt.md

@@ -0,0 +1,10 @@
+Generate a comprehensive report for the markdown file.
+
+File content: {{steps.analyze_file}}
+
+Patterns found: {{steps.analyze_patterns}}
+
+Please create a detailed report that includes:
+1. Summary of the file content
+2. Key patterns identified
+3. Any recommendations or observations

data/examples/no_model_fallback/generate_report_for_rb/prompt.md

@@ -0,0 +1,3 @@
+Generate a nicely formatted report based on the following metadata:
+
+<%= workflow.output[:analyze_patterns] %>

data/examples/no_model_fallback/sample.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Sample Ruby file for testing interpolation in workflows
+
+class Calculator
+  def initialize
+    @memory = 0
+  end
+
+  def add(number)
+    @memory += number
+  end
+
+  def subtract(number)
+    @memory -= number
+  end
+
+  def multiply(number)
+    @memory *= number
+  end
+
+  def divide(number)
+    raise "Division by zero!" if number.zero?
+
+    @memory /= number
+  end
+
+  attr_reader :memory
+
+  def clear
+    @memory = 0
+  end
+end
+
+# Example usage
+if __FILE__ == $PROGRAM_NAME
+  calc = Calculator.new
+  calc.add(10)
+  calc.multiply(2)
+  calc.subtract(5)
+  puts "Result: #{calc.memory}"
+end

data/examples/no_model_fallback/workflow.yml

@@ -0,0 +1,19 @@
+name: no_model_fallback_example
+
+tools:
+  - Roast::Tools::ReadFile
+
+steps:
+  - analyze_file
+  - analyze_patterns
+  - generate_report_for_{{File.extname(workflow.file).sub('.', '')}}
+  - '$(echo "Processing completed for file: {{File.basename(workflow.file)}}")'
+
+analyze_patterns:
+  json: true
+
+generate_report_for_rb:
+  print_response: true
+
+generate_report_for_md:
+  print_response: true

data/examples/swarm_example.yml

@@ -0,0 +1,25 @@
+name: Swarm Example Workflow
+
+# Example workflow demonstrating Roast's integration with Claude Swarm
+# The Swarm tool is available to the LLM, which can choose to use it when appropriate
+
+tools:
+  - Roast::Tools::Swarm:
+      path: ".swarm.yml"  # Optional - will use default locations if not specified
+
+steps:
+  - orchestrate_refactoring: |
+      Help me refactor this codebase for better performance. Coordinate multiple 
+      Claude agents using the swarm configuration to:
+      1. Analyze the current code structure
+      2. Identify performance bottlenecks
+      3. Implement optimizations
+      4. Ensure backward compatibility
+      
+  - specialized_analysis: |
+      Now use the specialized swarm configuration at ./specialized-swarm.yml to run 
+      a comprehensive code analysis that includes:
+      - Architecture review
+      - Security audit  
+      - Documentation generation
+      - Test coverage analysis

data/lib/roast/helpers/timeout_handler.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require "timeout"
+require "open3"
+
+module Roast
+  module Helpers
+    # Shared timeout handling logic for command-based tools
+    #
+    # This class provides centralized timeout functionality for executing shell commands
+    # with proper process management and resource cleanup.
+    #
+    # @example Basic usage
+    #   output, status = TimeoutHandler.call("echo hello", timeout: 5)
+    #
+    # @example With custom working directory
+    #   output, status = TimeoutHandler.call("pwd", timeout: 10, working_directory: "/tmp")
+    class TimeoutHandler
+      DEFAULT_TIMEOUT = 30
+      MAX_TIMEOUT = 300
+
+      class << self
+        # Execute a command with timeout using Open3 with proper process cleanup
+        # @param command [String] The command to execute
+        # @param timeout [Integer] Timeout in seconds
+        # @param working_directory [String] Directory to execute in (default: Dir.pwd)
+        # @return [Array<String, Integer>] [output, exit_status]
+        # @raise [Timeout::Error] When command exceeds timeout duration
+        def call(command, timeout: DEFAULT_TIMEOUT, working_directory: Dir.pwd)
+          timeout = validate_timeout(timeout)
+          output = ""
+          exit_status = nil
+          wait_thr = nil
+
+          begin
+            Timeout.timeout(timeout) do
+              stdin, stdout, stderr, wait_thr = Open3.popen3(command, chdir: working_directory)
+              stdin.close # Prevent hanging on stdin-waiting commands
+              output = stdout.read + stderr.read
+              wait_thr.join
+              exit_status = wait_thr.value.exitstatus
+
+              [stdout, stderr].each(&:close)
+            end
+          rescue Timeout::Error
+            # Clean up any remaining processes to prevent zombies
+            cleanup_process(wait_thr) if wait_thr&.alive?
+            raise Timeout::Error, "Command '#{command}' in '#{working_directory}' timed out after #{timeout} seconds"
+          end
+
+          [output, exit_status]
+        end
+
+        # Validate and normalize timeout value
+        # @param timeout [Integer, nil] Raw timeout value
+        # @return [Integer] Validated timeout between 1 and MAX_TIMEOUT
+        def validate_timeout(timeout)
+          return DEFAULT_TIMEOUT if timeout.nil? || timeout <= 0
+
+          [timeout, MAX_TIMEOUT].min
+        end
+
+        private
+
+        # Clean up process on timeout to prevent zombie processes
+        # @param wait_thr [Process::Waiter] The process thread to clean up
+        def cleanup_process(wait_thr)
+          return unless wait_thr&.alive?
+
+          pid = wait_thr.pid
+          # First try graceful termination
+          Process.kill("TERM", pid)
+          sleep(0.1)
+
+          # Force kill if still alive
+          if wait_thr.alive?
+            Process.kill("KILL", pid)
+          end
+        rescue Errno::ESRCH
+          # Process already terminated, which is fine
+        rescue Errno::EPERM
+          # Permission denied - process may be owned by different user
+          Roast::Helpers::Logger.debug("Could not kill process #{pid}: Permission denied")
+        rescue => e
+          # Catch any other unexpected errors during cleanup
+          Roast::Helpers::Logger.debug("Unexpected error during process cleanup: #{e.message}")
+        end
+      end
+    end
+  end
+end