roast-ai 0.4.2 → 0.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1822868d0357ade29fdbdd3feab6a1beff23ef97621de9e1a9cacee366d5897
-  data.tar.gz: 00b9aff47853dc8f1f4ffa89bf571975fbe414632909b682fe6caab4e64bee51
+  metadata.gz: 90d715c7be58b0ec9d6325f0eafd0b234d8bcf51fa3151c5830717dac034fdb5
+  data.tar.gz: d52615bc873667aaf3dc22a29c59b4ae0f6f1dd25af3addaaa4c8ad23eaa7cb4
 SHA512:
-  metadata.gz: 95c32a5e010460dfe2e584c7b0ba8b7d617dc965210fc00343bd2c1f647c847f3be41be0bb07a951a41b5aa1447c770b36f4eba97985543f510938044e85453b
-  data.tar.gz: d221ec8fba42b7187ae30fa4171e2700a7b81b1092693f9fdf1f168a37b6318482f5be8cf3f1be4e8650fe7a56d87ef2a0f93fea13f633e24c95734c285fd75b
+  metadata.gz: 80796feab187127b4815af1d6120f5370724e817c55ecc240b2f5c58c39faf63c2e7ccb65ebc58c427a09debea7c26fc2ba26a044450e8696901a5da9aaba4b9
+  data.tar.gz: fa9791f7148cad5177f756705eab8778f3925183f734537b5732d712513be494c7124a530e065b5ed40765c967361fd6d4a1ee62897b0ab34db334588f2dfb78

data/CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.3] - 2025-07-10
+
+### Changed
+- **Updated to raix-openai-eight gem** - Upgraded from `raix` to `raix-openai-eight` gem which supports OpenAI Ruby client v8.1
+
 ## [0.4.2] - 2025-06-20
 
 ### Added

data/Gemfile.lock

@@ -1,15 +1,14 @@
 PATH
   remote: .
   specs:
-    roast-ai (0.4.2)
+    roast-ai (0.4.4)
       activesupport (>= 7.0)
       cli-kit (~> 5.0)
       cli-ui (= 2.3.0)
       diff-lcs (~> 1.5)
-      faraday-retry
       json-schema
       open_router (~> 0.3)
-      raix (~> 1.0)
+      raix (~> 1.0.2)
       ruby-graphviz (~> 1.2)
       sqlite3 (~> 2.6)
       thor (~> 1.3)
@@ -93,13 +92,13 @@ GEM
       net-http (>= 0.5.0)
     faraday-retry (2.3.2)
       faraday (~> 2.0)
-    fast-mcp-annotations (1.5.2)
+    fast-mcp-annotations (1.5.3)
       addressable (~> 2.8)
       base64
       dry-schema (~> 1.14)
       json (~> 2.0)
       mime-types (~> 3.4)
-      rack (~> 3.1)
+      rack (< 3)
     ffi (1.17.2-arm64-darwin)
     ffi (1.17.2-x86_64-linux-gnu)
     formatador (1.1.0)
@@ -165,14 +164,14 @@ GEM
       method_source (~> 1.0)
     public_suffix (6.0.2)
     racc (1.8.1)
-    rack (3.1.16)
+    rack (2.2.17)
     rainbow (3.1.1)
-    raix (1.0.1)
+    raix (1.0.2)
       activesupport (>= 6.0)
       faraday-retry (~> 2.0)
       open_router (~> 0.2)
       ostruct
-      ruby-openai (~> 7)
+      ruby-openai (~> 8.1)
     rake (13.3.0)
     rb-fsevent (0.11.2)
     rb-inotify (0.11.1)
@@ -197,7 +196,7 @@ GEM
       rubocop (~> 1.62)
     ruby-graphviz (1.2.5)
       rexml
-    ruby-openai (7.4.0)
+    ruby-openai (8.1.0)
       event_stream_parser (>= 0.3.0, < 2.0.0)
       faraday (>= 1)
       faraday-multipart (>= 1)
@@ -205,9 +204,9 @@ GEM
     ruby2_keywords (0.0.5)
     securerandom (0.4.1)
     shellany (0.0.1)
-    sqlite3 (2.6.0-arm64-darwin)
-    sqlite3 (2.6.0-x86_64-linux-gnu)
-    thor (1.3.2)
+    sqlite3 (2.7.0-arm64-darwin)
+    sqlite3 (2.7.0-x86_64-linux-gnu)
+    thor (1.4.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
     unicode-display_width (3.1.4)

data/README.md

@@ -279,35 +279,126 @@ Roast supports several types of steps:
    ```
    Agent steps are prefixed with `^` and send the prompt content directly to the CodingAgent tool without LLM translation. This is useful when you want to give precise instructions to a coding agent without the intermediate interpretation layer. Agent steps support both file-based prompts (`fix_linting_errors/prompt.md`) and inline prompts (text with spaces).
 
-9. **Input step**: Interactive prompts for user input during workflow execution
+   **Session continuity for agent steps:**
+   
+   Agent steps support two options for maintaining Claude context across steps:
+   
+   1. **`continue: true`** - Continues from the immediately previous Claude Code session (note, if multiple Claude Code sessions are being run in parallel in the same working directory, this might not be the previous Claude Code session from this workflow) 
+   2. **`resume: step_name`** - Resumes from a specific earlier step's Claude Code session
+   
+   **Continue option:**
+   
+   The `continue` option allows sequential agent steps to maintain a continuous conversation:
+   
    ```yaml
    steps:
-     - analyze_code
-     - get_user_feedback:
-         prompt: "Should we proceed with the refactoring? (yes/no)"
-         type: confirm
-     - review_changes:
-         prompt: "Enter your review comments"
-         type: text
-     - select_strategy:
-         prompt: "Choose optimization strategy"
-         type: select
-         options:
-           - "Performance optimization"
-           - "Memory optimization"
-           - "Code clarity"
-     - api_configuration:
-         prompt: "Enter API key"
-         type: password
+     - ^analyze_codebase
+     - ^implement_feature
+     - ^add_tests
+   
+   # Configuration
+   analyze_codebase:
+     continue: false  # Start fresh (default)
+   
+   implement_feature:
+     continue: true   # Continue from immediately previous analyze_codebase step
+   
+   add_tests:
+     continue: true   # Continue from immediately previous implement_feature step
    ```
    
-   Input steps pause workflow execution to collect user input. They support several types:
-   - `text`: Free-form text input (default if type not specified)
-   - `confirm`: Yes/No confirmation prompts
-   - `select`: Choice from a list of options
-   - `password`: Masked input for sensitive data
+   **Resume functionality for agent steps:**
+   
+   Agent steps can resume from specific previous Claude Code sessions:
    
-   The user's input is stored in the workflow output using the step name as the key and can be accessed in subsequent steps via interpolation (e.g., `{{output.get_user_feedback}}`).
+   ```yaml
+   steps:
+     - ^analyze_codebase
+     - ^implement_feature
+     - ^polish_implementation
+   
+   # Configuration
+   analyze_codebase:
+     continue: false  # Start fresh
+   
+   implement_feature:
+     continue: true   # Continue from previous conversation
+   
+   polish_implementation:
+     resume: analyze_codebase  # Resume from a specific step's session not the immediately previous one
+   ```
+   
+   Note: Session IDs are only available when the CodingAgent is configured to output JSON format (includes `--output-format stream-json` in the command). If you are using a custom CodingAgent command that does not produce JSON output, resume functionality will not be available.
+
+   If `resume` is specified but the step name given does not have CodingAgent session to resume from, the CodingAgent will start Claude Code with a fresh session. 
+
+9. **Shell script step**: Execute shell scripts directly as workflow steps
+   ```yaml
+   steps:
+     - setup_environment     # Executes setup_environment.sh
+     - run_tests             # Executes run_tests.sh  
+     - cleanup
+   ```
+   
+   Shell script steps allow you to execute `.sh` files directly as workflow steps alongside Ruby steps and AI prompts. Scripts are automatically discovered in the same locations as other step types.
+   
+   **Configuration options:**
+   ```yaml
+   # Step configuration  
+   my_script:
+     json: true              # Parse stdout as JSON
+     exit_on_error: false    # Don't fail workflow on non-zero exit
+     env:                    # Custom environment variables
+       CUSTOM_VAR: "value"
+   ```
+   
+   **Environment integration:** Shell scripts automatically receive workflow context:
+   - `ROAST_WORKFLOW_RESOURCE`: Current workflow resource
+   - `ROAST_STEP_NAME`: Current step name
+   - `ROAST_WORKFLOW_OUTPUT`: Previous step outputs as JSON
+   
+   **Example script (`setup_environment.sh`):**
+   ```bash
+   #!/bin/bash
+   echo "Setting up environment for: $ROAST_WORKFLOW_RESOURCE"
+   
+   # Create a config file that subsequent steps can use
+   mkdir -p tmp
+   echo "DATABASE_URL=sqlite://test.db" > tmp/config.env
+   
+   # Output data for the workflow (available via ROAST_WORKFLOW_OUTPUT in later steps)
+   echo '{"status": "configured", "database": "sqlite://test.db", "config_file": "tmp/config.env"}'
+   ```
+
+10. **Input step**: Interactive prompts for user input during workflow execution
+    ```yaml
+    steps:
+      - analyze_code
+      - get_user_feedback:
+          prompt: "Should we proceed with the refactoring? (yes/no)"
+          type: confirm
+      - review_changes:
+          prompt: "Enter your review comments"
+          type: text
+      - select_strategy:
+          prompt: "Choose optimization strategy"
+          type: select
+          options:
+            - "Performance optimization"
+            - "Memory optimization"
+            - "Code clarity"
+      - api_configuration:
+          prompt: "Enter API key"
+          type: password
+    ```
+    
+    Input steps pause workflow execution to collect user input. They support several types:
+    - `text`: Free-form text input (default if type not specified)
+    - `confirm`: Yes/No confirmation prompts
+    - `select`: Choice from a list of options
+    - `password`: Masked input for sensitive data
+    
+    The user's input is stored in the workflow output using the step name as the key and can be accessed in subsequent steps via interpolation (e.g., `{{output.get_user_feedback}}`).
 
 #### Step Configuration
 
@@ -705,6 +796,100 @@ For most workflows, you'll mainly use `response` to access the current step's re
 
 ## Advanced Features
 
+### Workflow Metadata
+
+Roast workflows maintain a metadata store that allows steps to share structured data beyond the standard output hash. This is particularly useful for tracking state that needs to persist across steps but shouldn't be part of the conversation context.
+
+#### Setting Metadata
+
+Metadata can be set by custom Ruby steps that extend `BaseStep`:
+
+```ruby
+# workflow/analyze_codebase.rb
+class AnalyzeCodebase < Roast::Workflow::BaseStep
+   include Roast::Helpers::MetadataAccess
+   
+  def call
+    # Perform analysis
+    analysis_results = perform_deep_analysis
+    
+    # Store metadata for other steps to use
+    workflow.metadata[name.to_s] ||= {}
+    workflow.metadata[name.to_s]["total_files"] = analysis_results[:file_count]
+    workflow.metadata[name.to_s]["complexity_score"] = analysis_results[:complexity]
+    workflow.metadata[name.to_s]["analysis_id"] = SecureRandom.uuid
+    
+    # Return the normal output for the conversation
+    "Analyzed #{analysis_results[:file_count]} files with average complexity of #{analysis_results[:complexity]}"
+  end
+  
+  private
+  
+  def perform_deep_analysis
+    # Your analysis logic here
+    { file_count: 42, complexity: 7.5 }
+  end
+end
+```
+
+#### Accessing Metadata
+
+Metadata from previous steps can be accessed in:
+
+1. **Custom Ruby steps:**
+```ruby
+class GenerateReport < Roast::Workflow::BaseStep
+  def call
+    # Access metadata from a previous step
+    total_files = workflow.metadata.dig("analyze_codebase", "total_files")
+    complexity = workflow.metadata.dig("analyze_codebase", "complexity_score")
+    
+    "Generated report for #{total_files} files with complexity score: #{complexity}"
+  end
+end
+```
+
+2. **Workflow configuration via interpolation:**
+```yaml
+steps:
+  - analyze_codebase
+  - validate_threshold
+  - generate_report
+
+# Use metadata in step configuration
+validate_threshold:
+  if: "{{metadata.analyze_codebase.complexity_score > 8.0}}"
+  then:
+    - send_alert
+    - create_ticket
+  else:
+    - mark_as_passed
+
+# Pass metadata to command steps
+send_alert:
+  $(slack-notify "High complexity detected: {{metadata.analyze_codebase.complexity_score}}")
+```
+
+3. **Prompt templates (ERB):**
+```erb
+# In analyze_codebase/output.txt
+Analysis Summary:
+Files analyzed: <%= workflow.metadata.dig(name.to_s, "total_files") %>
+Complexity score: <%= workflow.metadata.dig(name.to_s, "complexity_score") %>
+Analysis ID: <%= workflow.metadata.dig(name.to_s, "analysis_id") %>
+```
+
+#### Metadata Best Practices
+
+- **Use metadata for data that shouldn't be in the conversation** 
+- **Don't duplicate output data:** Metadata complements the output hash, it doesn't replace it
+
+The metadata system is particularly useful for:
+- Tracking session or transaction IDs across multiple steps
+- Storing configuration or state that tools need to access
+- Passing data between steps without cluttering the AI conversation
+- Implementing complex conditional logic based on computed values
+
 ### Instrumentation
 
 Roast provides extensive instrumentation capabilities using ActiveSupport::Notifications. You can monitor workflow execution, track AI model usage, measure performance, and integrate with external monitoring systems. [Read the full instrumentation documentation](docs/INSTRUMENTATION.md).
@@ -727,11 +912,16 @@ tools:
         - yarn
   - Roast::Tools::CodingAgent:     # Optional configuration
       coding_agent_command: claude --model opus -p --allowedTools "Bash, Glob, Grep, LS, Read"
+      model: opus                  # Model to use for all CodingAgent invocations
+      retries: 3                   # Number of automatic retries on failure (default: 0)
 ```
 
 Currently supported configurations:
 - `Roast::Tools::Cmd` via `allowed_commands`: restricts which commands can be executed (defaults to: `pwd`, `find`, `ls`, `rake`, `ruby`, `dev`, `mkdir`)
-- `Roast::Tools::CodingAgent` via `coding_agent_command`: customizes the Claude Code CLI command used by the agent
+- `Roast::Tools::CodingAgent` via:
+  - `coding_agent_command`: customizes the Claude Code CLI command used by the agent
+  - `model`: sets the model for all CodingAgent invocations (e.g., `opus`, `sonnet`)
+  - `retries`: number of times to automatically retry if the agent encounters an error (default: 0, no retries)
 
 ##### Cmd Tool Configuration
 
@@ -959,16 +1149,25 @@ bash(command: "ps aux | grep ruby | awk '{print $2}'")
 Creates a specialized agent for complex coding tasks or long-running operations.
 
 ```ruby
+# Basic usage
+coding_agent(
+  prompt: "Refactor the authentication module to use JWT tokens",
+  include_context_summary: true,  # Include workflow context in the agent prompt
+  continue: true                  # Continue from previous agent session
+)
+
+# With automatic retries on failure
 coding_agent(
-  task: "Refactor the authentication module to use JWT tokens",
-  language: "ruby",
-  files: ["app/models/user.rb", "app/controllers/auth_controller.rb"]
+  prompt: "Implement complex feature with error handling",
+  retries: 3  # Retry up to 3 times if the agent encounters errors
 )
 ```
 
-- Delegates complex tasks to a specialized coding agent
+- Delegates complex tasks to a specialized coding agent (Claude Code)
 - Useful for tasks that require deep code understanding or multi-step changes
 - Can work across multiple files and languages
+- Supports automatic retries on transient failures (network issues, API errors)
+- Retries can be configured globally (see Tool Configuration) or per invocation
 
 ### MCP (Model Context Protocol) Tools
 

data/examples/coding_agent_with_model.yml

@@ -0,0 +1,20 @@
+name: CodingAgent with Model Configuration
+description: |
+  Example workflow demonstrating how to configure the CodingAgent tool
+  with specific model options like opus
+
+tools:
+  - Roast::Tools::CodingAgent:
+      model: opus
+      # You can also add other claude options here:
+      # temperature: 0.7
+      # max_tokens: 1000
+
+steps:
+  - analyze_code: |
+      Analyze the Ruby code in lib/roast/tools/coding_agent.rb
+      and explain how the CodingAgent tool works.
+      
+  - implement_feature: |
+      Create a simple Ruby script that demonstrates using command-line
+      options similar to how CodingAgent builds its commands.

data/examples/coding_agent_with_retries.yml

@@ -0,0 +1,30 @@
+name: CodingAgent with Retries Configuration
+description: |
+  Example workflow demonstrating how to configure the CodingAgent tool
+  with automatic retries on failure. The retries option will automatically
+  retry the coding agent if it encounters an error during execution.
+  Note: this is not the same as running the step
+
+tools:
+  - Roast::Tools::CodingAgent:
+      retries: 2  # Automatically retry up to 2 times on failure
+
+steps:
+  # This step invokes the coding agent directly using the specified number of retries
+  - ^implement_a_feature: |
+      Create a Ruby script that demonstrates robust error handling.
+      The script should:
+      1. Attempt to read a file that might not exist
+      2. Handle any errors gracefully
+      3. Log the results
+
+
+  # This step invokes the general workflow LLM which can in turn invoke the coding agent.
+  # When the general LLM invokes the coding agent, it will execute with the specified number of retries.
+  - add_tests: |
+      Add test for the feature you just implemented.
+      Run the tests and iterate until they all pass.
+      Use the CodingAgent tool to write the tests.
+
+add_tests:
+  retries: 4

data/lib/roast/helpers/metadata_access.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Roast
+  module Helpers
+    module MetadataAccess
+      def step_metadata(step_name = nil)
+        step_name ||= current_step_name
+        return {} unless step_name
+
+        metadata = workflow_metadata || {}
+        metadata[step_name] || {}
+      end
+
+      def set_current_step_metadata(key, value)
+        step_name = current_step_name
+        metadata = workflow_metadata
+
+        return unless step_name && metadata
+
+        metadata[step_name] ||= {}
+        metadata[step_name][key] = value
+      end
+
+      private
+
+      def workflow_metadata
+        metadata = Thread.current[:workflow_metadata]
+        Roast::Helpers::Logger.warn("MetadataAccess#workflow_metadata is not present") if metadata.nil?
+        metadata
+      end
+
+      def current_step_name
+        step_name = Thread.current[:current_step_name]
+        Roast::Helpers::Logger.warn("MetadataAccess#current_step_name is not present") if step_name.nil?
+        step_name
+      end
+    end
+  end
+end

data/lib/roast/helpers/timeout_handler.rb

@@ -17,7 +17,7 @@ module Roast
     #   output, status = TimeoutHandler.call("pwd", timeout: 10, working_directory: "/tmp")
     class TimeoutHandler
       DEFAULT_TIMEOUT = 30
-      MAX_TIMEOUT = 300
+      MAX_TIMEOUT = 3600
 
       class << self
         # Execute a command with timeout using Open3 with proper process cleanup