roast-ai 1.2.0 → 1.4.0

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

@@ -5,6 +5,14 @@ module Roast
   module Cogs
     class Chat < Cog
       class Config < Cog::Config
+        # Environment variable that overrides the built-in default chat provider.
+        #
+        # When a chat cog does not explicitly configure a provider, Roast uses the provider named by
+        # this variable, falling back to the built-in default (`PROVIDERS.keys.first`, i.e. `:openai`) 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_CHAT_PROVIDER" #: String
+
         PROVIDERS = {
           openai: {
             api_key_env_var: "OPENAI_API_KEY",
@@ -28,6 +36,10 @@ module Roast
             default_base_url: "https://generativelanguage.googleapis.com/v1beta",
             default_model: "gemini-3.1-flash-lite",
           },
+          bedrock: {
+            api_key_env_var: "AWS_ACCESS_KEY_ID",
+            default_model: "us.anthropic.claude-haiku-4-5-20251001-v1:0",
+          },
         }.freeze #: Hash[Symbol, Hash[Symbol, String]]
 
         # Configure the cog to use a specified API provider when invoking the llm
@@ -42,7 +54,8 @@ module Roast
 
         # Configure the cog to use the default provider when invoking the llm
         #
-        # The default LLM provider used by Roast is OpenAI (`:openai`).
+        # The default LLM provider is the one named by the `ROAST_DEFAULT_CHAT_PROVIDER` environment
+        # variable, or OpenAI (`:openai`) when that variable is unset.
         #
         # #### See Also
         # - `provider`
@@ -54,6 +67,10 @@ module Roast
 
         # Get the validated provider name that the cog is configured to use when invoking the llm
         #
+        # The provider is resolved in order of precedence: the provider explicitly configured on the cog,
+        # then the `ROAST_DEFAULT_CHAT_PROVIDER` environment variable (normalized by stripping surrounding
+        # whitespace and downcasing), then the built-in default (`PROVIDERS.keys.first`, i.e. `:openai`).
+        #
         # Note: this method will return the name of a valid provider or raise an `InvalidConfigError`.
         # It will __not__, however, validate that the you have access to the provider's API.
         # If you have not correctly configured API access, you will likely experience a failure when Roast attempts to
@@ -65,7 +82,8 @@ module Roast
         #
         #: () -> Symbol
         def valid_provider!
-          provider = @values[:provider] || PROVIDERS.keys.first
+          env_default = ENV[DEFAULT_PROVIDER_ENV_VAR].presence&.strip&.downcase&.to_sym
+          provider = @values[:provider] || env_default || PROVIDERS.keys.first
           unless PROVIDERS.include?(provider)
             raise InvalidConfigError, "'#{provider}' is not a valid provider. Available providers include: #{PROVIDERS.keys.join(", ")}"
           end
@@ -94,6 +112,7 @@ module Roast
         # - Anthropic Provider: ANTHROPIC_API_KEY
         # - Perplexity Provider: PERPLEXITY_API_KEY
         # - Gemini Provider: GEMINI_API_KEY
+        # - Bedrock Provider: AWS_ACCESS_KEY_ID
         #
         # #### See Also
         # - `api_key`
@@ -113,6 +132,7 @@ module Roast
         # - Anthropic Provider: ANTHROPIC_API_KEY
         # - Perplexity Provider: PERPLEXITY_API_KEY
         # - Gemini Provider: GEMINI_API_KEY
+        # - Bedrock Provider: AWS_ACCESS_KEY_ID
         #
         # #### See Also
         # - `api_key`
@@ -176,6 +196,37 @@ module Roast
             PROVIDERS.dig(valid_provider!, :default_base_url)
         end
 
+        # Get the AWS secret access key used to sign requests when the Bedrock provider is selected
+        #
+        # Only the Bedrock provider uses this value. It is read from the `AWS_SECRET_ACCESS_KEY` environment variable.
+        # This method will raise InvalidConfigError if that variable is unset or blank.
+        #
+        #: () -> String
+        def valid_aws_secret_access_key!
+          ENV["AWS_SECRET_ACCESS_KEY"].presence || raise(InvalidConfigError, "AWS_SECRET_ACCESS_KEY is not set")
+        end
+
+        # Get the AWS session token used to sign requests with temporary credentials, such as those from AWS SSO
+        #
+        # Only the Bedrock provider uses this value. It is read from the `AWS_SESSION_TOKEN` environment variable.
+        # Returns nil if that variable is unset or blank, because long-term credentials need no session token.
+        #
+        #: () -> String?
+        def valid_aws_session_token
+          ENV["AWS_SESSION_TOKEN"].presence
+        end
+
+        # Get the AWS region that the Bedrock provider sends requests to
+        #
+        # Only the Bedrock provider uses this value. It is read from the `AWS_REGION` environment variable only.
+        # `AWS_DEFAULT_REGION` is ignored, so that a region left in a shell profile never selects a region silently.
+        # This method will raise InvalidConfigError if `AWS_REGION` is unset or blank.
+        #
+        #: () -> String
+        def valid_aws_region!
+          ENV["AWS_REGION"].presence || raise(InvalidConfigError, "AWS_REGION is not set")
+        end
+
         # Configure the cog to use a specific model when invoking the agent
         #
         # The model name format is provider-specific.

data/lib/roast/cogs/chat.rb

@@ -59,16 +59,19 @@ module Roast
             Event << { block: { header: "UNKNOWN", content: message.content } } if config.show_prompt? || config.show_response?
           end
         end
+        # The Bedrock Converse response has no modelId field, so ruby_llm leaves response.model_id nil for it.
+        # The chat model holds the ID that ruby_llm sent.
+        model_id = response.model_id || chat.model.id
         if config.show_stats?
           temperature = chat.instance_variable_get(:@temperature)
-          lines = ["Model: #{response.model_id}"]
+          lines = ["Model: #{model_id}"]
           lines << "Temperature: #{format("%0.2f", temperature)}" if temperature
           lines << "Input Tokens: #{response.input_tokens}"
           lines << "Output Tokens: #{response.output_tokens}"
           Event << { block: { header: "LLM STATS", content: lines.join("\n") } }
         end
 
-        verify_response_not_truncated!(response)
+        verify_response_not_truncated!(response, model_id)
 
         Output.new(Session.from_chat(chat), response.content)
       end
@@ -95,15 +98,15 @@ module Roast
       # on a natural boundary. This is an unavoidable trade-off of the heuristic approach until
       # ruby_llm exposes finish_reason.
       #
-      #: (RubyLLM::Message) -> void
-      def verify_response_not_truncated!(response)
+      #: (RubyLLM::Message, String) -> void
+      def verify_response_not_truncated!(response, model_id)
         max_tokens = effective_max_tokens
         return unless max_tokens
         return unless response.output_tokens
 
         if response.output_tokens >= max_tokens
           raise MaxTokensExceededError,
-            "LLM response from #{response.model_id} was truncated at the max token limit " \
+            "LLM response from #{model_id} was truncated at the max token limit " \
               "(output: #{response.output_tokens} tokens, limit: #{max_tokens} tokens). " \
               "The response content is likely incomplete and should not be used."
         end
@@ -143,6 +146,11 @@ module Roast
           when :gemini
             context.gemini_api_key = config.valid_api_key!
             context.gemini_api_base = config.valid_base_url
+          when :bedrock
+            context.bedrock_api_key = config.valid_api_key!
+            context.bedrock_secret_key = config.valid_aws_secret_access_key!
+            context.bedrock_session_token = config.valid_aws_session_token
+            context.bedrock_region = config.valid_aws_region!
           end
         end
       end

data/lib/roast/cogs/cmd.rb

@@ -168,6 +168,40 @@ module Roast
           show_stdout? || show_stderr?
         end
 
+        # Configure the cog to run the command with these environment variables set
+        #
+        # Variables not named here are inherited from Roast's own environment. A `nil` value unsets
+        # the variable for the command.
+        #
+        # #### See Also
+        # - `no_env!`
+        #
+        #: (Hash[String | Symbol, String?]) -> void
+        def env(vars)
+          @values[:env] = vars
+        end
+
+        # Configure the cog to run the command with Roast's own environment, unchanged (the default)
+        #
+        # #### See Also
+        # - `env`
+        #
+        #: () -> void
+        def no_env!
+          @values[:env] = nil
+        end
+
+        # Get the validated environment variables the command will be run with, keyed by name
+        #
+        # #### See Also
+        # - `env`
+        # - `no_env!`
+        #
+        #: () -> Hash[String, String?]
+        def valid_env
+          (@values[:env] || {}).to_h { |name, value| [name.to_s, value&.to_s] }
+        end
+
         alias_method(:quiet!, :no_display!)
       end
 
@@ -281,6 +315,7 @@ module Roast
           .execute(
             [input.command] + input.args,
             working_directory: config.valid_working_directory,
+            env: config.valid_env,
             stdin_content: input.stdin,
             stdout_handler: stdout_handler,
             stderr_handler: stderr_handler,

data/lib/roast/command_runner.rb

@@ -45,6 +45,7 @@ module Roast
       #: (
       #|  Array[String],
       #|  ?working_directory: (Pathname | String)?,
+      #|  ?env: Hash[String, String?],
       #|  ?timeout: (Integer | Float)?,
       #|  ?stdin_content: String?,
       #|  ?stdout_handler: (^(String) -> void)?,
@@ -53,6 +54,7 @@ module Roast
       def execute(
         args,
         working_directory: nil,
+        env: {},
         timeout: nil,
         stdin_content: nil,
         stdout_handler: nil,
@@ -69,7 +71,7 @@ module Roast
         stdin, stdout, stderr, wait_thread = Bundler.with_unbundled_env do
           Open3 #: as untyped
             .popen3(
-              env_overrides.merge({ "PWD" => working_directory&.to_s }).compact,
+              env.merge(env_overrides, { "PWD" => working_directory&.to_s }.compact),
               *args.map(&:to_s),
               { chdir: working_directory }.compact,
             )

data/lib/roast/config_manager.rb

@@ -3,15 +3,18 @@
 
 module Roast
   class ConfigManager
+    include WorkflowParamAccessors
+
     class ConfigManagerError < Roast::Error; end
     class ConfigManagerNotPreparedError < ConfigManagerError; end
     class ConfigManagerAlreadyPreparedError < ConfigManagerError; end
     class IllegalCogNameError < ConfigManagerError; end
 
-    #: (Cog::Registry, Array[^() -> void]) -> void
-    def initialize(cog_registry, config_procs)
+    #: (Cog::Registry, Array[^() -> void], WorkflowContext) -> void
+    def initialize(cog_registry, config_procs, workflow_context)
       @cog_registry = cog_registry
       @config_procs = config_procs
+      @workflow_context = workflow_context
       @config_context = ConfigContext.new #: ConfigContext
       @global_config = Cog::Config.new #: Cog::Config
       @general_configs = {} #: Hash[singleton(Cog), Cog::Config]
@@ -117,6 +120,7 @@ module Roast
       # NOTE: Sorbet expects the proc passed to instance_exec to be declared as taking an argument
       # but our cog_config_proc does not get an argument
       cog_config_proc = cog_config_proc #: as ^(untyped) -> void
+      bind_workflow_params(config_object)
       config_object.instance_exec(&cog_config_proc) if cog_config_proc
       nil
     end
@@ -134,8 +138,31 @@ module Roast
     #: (^() -> void ) -> void
     def on_global(global_config_proc)
       global_config_proc = global_config_proc #: as ^(untyped) -> void
+      bind_workflow_params(@global_config)
       @global_config.instance_exec(&global_config_proc) if global_config_proc
       nil
     end
+
+    #: (Cog::Config) -> void
+    def bind_workflow_params(object)
+      target_bang_method = method(:target!)
+      targets_method = method(:targets)
+      arg_question_method = method(:arg?)
+      args_method = method(:args)
+      kwarg_method = method(:kwarg)
+      kwarg_bang_method = method(:kwarg!)
+      kwarg_question_method = method(:kwarg?)
+      kwargs_method = method(:kwargs)
+      object.instance_eval do
+        define_singleton_method(:target!, proc { target_bang_method.call })
+        define_singleton_method(:targets, proc { targets_method.call })
+        define_singleton_method(:arg?, proc { |value| arg_question_method.call(value) })
+        define_singleton_method(:args, proc { args_method.call })
+        define_singleton_method(:kwarg, proc { |key| kwarg_method.call(key) })
+        define_singleton_method(:kwarg!, proc { |key| kwarg_bang_method.call(key) })
+        define_singleton_method(:kwarg?, proc { |key| kwarg_question_method.call(key) })
+        define_singleton_method(:kwargs, proc { kwargs_method.call })
+      end
+    end
   end
 end

data/lib/roast/version.rb

@@ -2,5 +2,5 @@
 # frozen_string_literal: true
 
 module Roast
-  VERSION = "1.2.0"
+  VERSION = "1.4.0"
 end

data/lib/roast/workflow.rb

@@ -19,12 +19,15 @@ module Roast
         Sync do
           Dir.mktmpdir("roast-") do |tmpdir|
             EventMonitor.start!
-            workflow_dir = Pathname.new(workflow_path).dirname
-            workflow_context = WorkflowContext.new(params: params, tmpdir: tmpdir, workflow_dir: workflow_dir)
-            workflow = new(workflow_path, workflow_context)
-            workflow.prepare!
-            workflow.start!
-            EventMonitor.stop!
+            begin
+              workflow_dir = Pathname.new(workflow_path).dirname
+              workflow_context = WorkflowContext.new(params: params, tmpdir: tmpdir, workflow_dir: workflow_dir)
+              workflow = new(workflow_path, workflow_context)
+              workflow.prepare!
+              workflow.start!
+            ensure
+              EventMonitor.stop! if EventMonitor.running?
+            end
           end
         end
       end
@@ -48,7 +51,7 @@ module Roast
 
       @preparing = true
       extract_dsl_procs!
-      @config_manager = ConfigManager.new(@cog_registry, @config_procs)
+      @config_manager = ConfigManager.new(@cog_registry, @config_procs, @workflow_context)
       @config_manager.not_nil!.prepare!
       # TODO: probably we should just not pass the params as the top-level scope value anymore
       @execution_manager = ExecutionManager.new(@cog_registry, @config_manager.not_nil!, @execution_procs, @workflow_context, scope_value: @workflow_context.params)

data/lib/roast/workflow_param_accessors.rb

@@ -0,0 +1,53 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  # @requires_ancestor: Kernel
+  module WorkflowParamAccessors
+    private
+
+    #: () -> 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
+  end
+end

data/sorbet/rbi/shims/lib/roast/cog/config.rbi

@@ -0,0 +1,251 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  class Cog
+    class Config
+      ########################################
+      #             Workflow Methods
+      ########################################
+
+      # Get the single target value passed to the workflow
+      #
+      # Returns the target when exactly one target was provided to the workflow. Raises an
+      # `ArgumentError` if the workflow was invoked with zero or multiple targets.
+      #
+      # Targets are file paths, URLs, or other identifiers passed to the workflow when it is
+      # invoked. Use this method when your workflow expects exactly one target.
+      #
+      # ### Invocation
+      # Invoke a workflow with a single target like this:
+      # ```bash
+      # roast execute my_workflow.rb my_target_file.txt
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     # Configure based on the single target
+      #     temperature(target!.end_with?(".md") ? 0.7 : 0.2)
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `targets` - Get all targets as an array (works with any number of targets)
+      #
+      #: () -> String
+      def target!; end
+
+      # Get all targets passed to the workflow
+      #
+      # Returns an array of all targets provided to the workflow. Works with any number of targets
+      # (zero, one, or many). Targets are file paths, URLs, or other identifiers passed when the
+      # workflow is invoked.
+      #
+      # ### Invocation
+      # Invoke a workflow with multiple targets like this:
+      # ```bash
+      # roast execute my_workflow.rb target_one.txt target_two.txt
+      # ```
+      # or using shell globs like this:
+      # ```bash
+      # roast execute my_workflow.rb target_*.txt
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   map do
+      #     # Process targets in parallel when there are several
+      #     parallel! if targets.length > 3
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `target!` - Get the single target (raises an error if there isn't exactly one)
+      #
+      #: () -> Array[String]
+      def targets; end
+
+      # Check if a flag argument was passed to the workflow
+      #
+      # Returns `true` if the specified flag argument symbol was provided when the workflow
+      # was invoked, `false` otherwise.
+      #
+      # Flag arguments are symbolic flags passed to the workflow (e.g., `retry`, `force`)
+      # that enable or modify behavior.
+      #
+      # ### Invocation
+      # Invoke a workflow with flag arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- retry force
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     # Pick a cheaper model when invoked with the `fast` flag
+      #     model(arg?(:fast) ? "gpt-5.4-nano" : "gpt-5")
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `args` - Get all flag arguments as an array
+      # - `kwarg?` - Check for keyword arguments (key-value pairs)
+      #
+      #: (Symbol) -> bool
+      def arg?(value); end
+
+      # Get all flag arguments passed to the workflow
+      #
+      # Returns an array of all flag argument symbols provided when the workflow was invoked.
+      # Flag arguments are symbolic flags (e.g., `retry`, `force`) that enable or modify
+      # workflow behavior.
+      #
+      # ### Invocation
+      # Invoke a workflow with flag arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- retry force
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   global do
+      #     # Show full output whenever any flags were passed
+      #     display! unless args.empty?
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `arg?` - Check if a specific flag argument was provided
+      # - `kwargs` - Get all keyword arguments
+      #
+      #: () -> Array[Symbol]
+      def args; end
+
+      # Get a keyword argument value passed to the workflow
+      #
+      # Returns the string value for the specified keyword argument key, or `nil` if the key was
+      # not provided. Keyword arguments are key-value pairs passed to the workflow for configuration.
+      #
+      # ### Invocation
+      # Invoke a workflow with keyword arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- name=Samantha project=Roast
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     # Use a provided model override, or fall back to a default
+      #     model(kwarg(:model) || "gpt-5")
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `kwarg!` - Get a keyword argument value (raises an error if not provided)
+      # - `kwarg?` - Check if a keyword argument was provided
+      # - `kwargs` - Get all keyword arguments as a hash
+      #
+      #: (Symbol) -> String?
+      def kwarg(key); end
+
+      # Get a required keyword argument value passed to the workflow
+      #
+      # Returns the string value for the specified keyword argument key. Raises an `ArgumentError`
+      # if the key was not provided.
+      #
+      # Use this when your workflow requires a specific keyword argument to function correctly.
+      #
+      # ### Invocation
+      # Invoke a workflow with keyword arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- name=Samantha project=Roast
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     # Require the 'model' keyword argument
+      #     model(kwarg!(:model))
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `kwarg` - Get a keyword argument value (returns nil if not provided)
+      # - `kwarg?` - Check if a keyword argument was provided
+      # - `kwargs` - Get all keyword arguments as a hash
+      #
+      #: (Symbol) -> String
+      def kwarg!(key); end
+
+      # Check if a keyword argument was passed to the workflow
+      #
+      # Returns `true` if the specified keyword argument key was provided when the workflow was
+      # invoked, `false` otherwise.
+      #
+      # ### Invocation
+      # Invoke a workflow with keyword arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- name=Samantha project=Roast
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     temperature(0.9) if kwarg?(:creative)
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `kwarg` - Get a keyword argument value (returns nil if not provided)
+      # - `kwarg!` - Get a keyword argument value (raises an error if not provided)
+      # - `kwargs` - Get all keyword arguments as a hash
+      #
+      #: (Symbol) -> bool
+      def kwarg?(key); end
+
+      # Get all keyword arguments passed to the workflow
+      #
+      # Returns a hash of all keyword argument key-value pairs provided when the workflow was invoked.
+      # All keys are symbols and all values are strings.
+      #
+      # ### Invocation
+      # Invoke a workflow with keyword arguments like this:
+      # ```bash
+      # roast execute my_workflow.rb [TARGETS] -- name=Samantha project=Roast
+      # ```
+      #
+      # ### Usage
+      # ```ruby
+      # config do
+      #   chat do
+      #     model(kwargs[:model] || "gpt-5")
+      #     temperature(kwargs[:temperature]&.to_f || 0.3)
+      #   end
+      # end
+      # ```
+      #
+      # #### See Also
+      # - `kwarg` - Get a single keyword argument value
+      # - `kwarg!` - Get a required keyword argument value
+      # - `kwarg?` - Check if a keyword argument was provided
+      #
+      #: () -> Hash[Symbol, String]
+      def kwargs; end
+    end
+  end
+end

data/sorbet/rbi/shims/lib/roast/config_context.rbi

@@ -141,7 +141,7 @@ module Roast
     #
     # #### Configure the agent provider
     # - `provider(symbol)` - Set the agent provider (e.g., `:claude`)
-    # - `use_default_provider!` - Use the default provider (`:claude`)
+    # - `use_default_provider!` - Use the default provider (`:pi`, or `$ROAST_DEFAULT_AGENT_PROVIDER` when set)
     #
     # #### Configure the base command used to run the coding agent
     # - `command(string_or_array)` - Set the base command for invoking the agent
@@ -151,6 +151,10 @@ module Roast
     # - `model(string)` - Set the model to use
     # - `use_default_model!` - Use the provider's default model
     #
+    # #### Configure a time limit
+    # - `timeout(seconds)` - Kill the agent and fail the cog if it runs longer than this
+    # - `no_timeout!` - Let the agent run for as long as it takes (default)
+    #
     # #### Configure the system prompt
     # - `replace_system_prompt(string)` - Completely replace the agent's default system prompt
     # - `no_replace_system_prompt!` - Don't replace the default system prompt (default)
@@ -180,6 +184,10 @@ module Roast
     # #### Configure debugging
     # - `dump_raw_agent_messages_to(filename)` - Dump raw agent messages to a file for debugging
     #
+    # #### Configure run records
+    # - `record_agent_runs_to(filename)` - Append a JSON record of each agent run (prompts, response, session, stats, status) to a file
+    # - `no_record_agent_runs!` - Don't record agent runs (default)
+    #
     # #### Configure asynchronous execution
     # - `async!` - Run the cog asynchronously in the background
     # - `no_async!` (alias `sync!`) - Run the cog synchronously (default)
@@ -269,6 +277,10 @@ module Roast
     # - `fail_on_error!` - Consider the cog failed if the command returns a non-zero exit status (default)
     # - `no_fail_on_error!` - Don't fail the cog on non-zero exit status (exit status still available in output)
     #
+    # #### Configure the environment
+    # - `env(hash)` - Set environment variables for the command (a `nil` value unsets one)
+    # - `no_env!` - Run the command with Roast's own environment, unchanged (default)
+    #
     # #### Configure display output
     # - `show_stdout!` - Write STDOUT to the console
     # - `no_show_stdout!` - Don't write STDOUT to the console (default)