roast-ai 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1986abc657a0e2c822c55ee0d5f2b2682c1e5cfed5a2d5f22e535a17fb074863
-  data.tar.gz: 59c0f6d1ac0c23a54e3ae05a7e1c0739da7355e8fd859b857670abc9887f7dd5
+  metadata.gz: a5ba7cc0a49bb69453853fcd6f4e2976d06260a9fc0c5c949007f313fba05a24
+  data.tar.gz: bd2a41c501b808ccea6970c7cb2af195848708fc23acb2c35aae6fa3a143b05d
 SHA512:
-  metadata.gz: 59a575e029f23d5e599755effbca910ff7e7853095c4eee445e74c65ad7bfcff57c5c4e43a4a7c8df402660def83b33dffcd88b0280a018edf31206575aafdf0
-  data.tar.gz: 0dced7351e53860f44a105e6604282583903953c85f25c5bffc03acc1d5785ad556c0be5473da514d827b17ff5acce295ae8447b2a434b311809c75832c36327
+  metadata.gz: 475cd2ca97a13f701fd4c699257090b2b89b559bde22b1391506daa8c876dbbd6a3d2711d6e46a2a22f34db1c83477a373728575eeb9178c113447ec624048d5
+  data.tar.gz: 4a68745484d9aa4da868cf99340eb27578d507c632a2d935c5e6aa5dc037501db56ed271042f295d0e3d8a4e8247cef9eec5aaa66dad02295a9e020cd2d3085f

data/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: .
   specs:
-    roast-ai (1.0.0)
+    roast-ai (1.0.1)
       activesupport (~> 8.0)
       async (>= 2.34)
+      rainbow (>= 3.0.0)
       ruby_llm (>= 1.8)
       zeitwerk (>= 2.6)
 

data/examples/console_output.rb

@@ -0,0 +1,13 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::Workflow
+
+config do
+  cmd { display! }
+end
+
+execute do
+  cmd(:out) { "echo hello world" }
+  cmd(:err) { "echo goodnight moon >&2" }
+end

data/examples/custom_logging.rb

@@ -0,0 +1,27 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::Workflow
+
+# By default, Roast logs to standard error at the WARN level. You can easily override this with the ROAST_LOG_LEVEL
+# environment variable, without having to touch the logger's configuration itself.
+#   Valid levels are DEBUG, INFO, WARN, ERROR, or FATAL (not case-sensitive).
+# For more advanced configuration, such as configuring a custom log formatter, or logging to a custom output location,
+# you can configure ore replace  the logger instance used by Roast (Roast::Log.logger)
+
+# Log to standard output, always at the DEBUG level
+Roast::Log.logger = Logger.new($stdout).tap { |logger| logger.level = ::Logger::DEBUG }
+
+# Format log lines in a particular way
+Roast::Log.logger.formatter = proc do |severity, time, progname, msg|
+  "#{severity[0..0]}, #{msg.strip} (at #{time})\n"
+end
+
+
+config do
+  cmd(:echo) { display! }
+end
+
+execute do
+  cmd(:echo) { "echo hello world" }
+end

data/examples/demo/Gemfile.lock

@@ -1,9 +1,10 @@
 PATH
   remote: ../..
   specs:
-    roast-ai (1.0.0)
+    roast-ai (1.0.1)
       activesupport (~> 8.0)
       async (>= 2.34)
+      rainbow (>= 3.0.0)
       ruby_llm (>= 1.8)
       zeitwerk (>= 2.6)
 
@@ -71,6 +72,7 @@ GEM
     multipart-post (2.4.1)
     net-http (0.9.1)
       uri (>= 0.11.1)
+    rainbow (3.1.1)
     ruby_llm (1.8.2)
       base64
       event_stream_parser (~> 1)

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

@@ -1,9 +1,10 @@
 PATH
   remote: ../..
   specs:
-    roast-ai (1.0.0)
+    roast-ai (1.0.1)
       activesupport (~> 8.0)
       async (>= 2.34)
+      rainbow (>= 3.0.0)
       ruby_llm (>= 1.8)
       zeitwerk (>= 2.6)
 

data/examples/shell_sanitization.rb

@@ -0,0 +1,37 @@
+# typed: true
+# frozen_string_literal: true
+
+#: self as Roast::Workflow
+
+# If you have untrusted strings you want to use in `cmd` cog shell commands,
+# you have several built-in options for safety
+
+config do
+  cmd { display! }
+end
+
+execute do
+  cmd(:attack_succeeds) do
+    bad_param = "; echo bad"
+    "echo hello world #{bad_param}"
+  end
+
+  cmd(:attack_fails_because_of_sanitization) do
+    # Use `.shellescape` on any untrusted strings you're interpolating into shell command strings
+    bad_param = "; echo bad"
+    "echo hello world #{bad_param.shellescape}"
+  end
+
+  cmd(:attack_fails_because_of_explicit_args) do |my|
+    # Use an array of arguments instead of string interpolation. This skips the shell entirely and just run the command.
+    bad_param = "; echo bad"
+    my.command = "echo"
+    my.args = ["hello", "world", bad_param]
+  end
+
+  cmd(:attack_fails_because_of_explicit_args_shorthand) do
+    # Simply returning an array instead of a string is convenient shorthand
+    bad_param = "; echo bad"
+    ["echo", "hello", "world", bad_param]
+  end
+end

data/lib/roast/cog.rb

@@ -44,9 +44,10 @@ module Roast
     #: Cog::Output?
     attr_reader :output
 
-    #: (Symbol, ^(Cog::Input) -> untyped) -> void
-    def initialize(name, cog_input_proc)
+    #: (Symbol, ^(Cog::Input) -> untyped, ?anonymous: bool) -> void
+    def initialize(name, cog_input_proc, anonymous: false)
       @name = name
+      @anonymous = anonymous
       @cog_input_proc = cog_input_proc #: ^(Cog::Input) -> untyped
       @output = nil #: Cog::Output?
       @skipped = false #: bool
@@ -56,12 +57,23 @@ module Roast
       @config = self.class.config_class.new #: untyped
     end
 
+    #: () -> bool
+    def anonymous?
+      @anonymous
+    end
+
+    #: () -> String
+    def type
+      self.class.name.not_nil!.demodulize.underscore
+    end
+
     #: (Async::Barrier, Cog::Config, CogInputContext, untyped, Integer) -> Async::Task
     def run!(barrier, config, input_context, executor_scope_value, executor_scope_index)
       raise CogAlreadyStartedError if @task
 
       @task = barrier.async(finished: false) do |task|
-        task.annotate("#{self.class.name.not_nil!.demodulize.camelcase} Cog: #{@name}")
+        task.annotate("Cog #{type}(:#{@name})")
+        TaskContext.begin_cog(self)
         @config = config
         input_instance = self.class.input_class.new
         input_return = input_context.instance_exec(
@@ -84,6 +96,8 @@ module Roast
       rescue StandardError => e
         @failed = true
         raise e
+      ensure
+        TaskContext.end
       end
     end
 

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

@@ -158,6 +158,8 @@ module Roast
                 Roast::Log.debug("[FULL MESSAGE: #{message.type}]")
                 Roast::Log.debug(message.inspect)
               end
+
+              raise ClaudeFailedError, message.error if message.error.present?
             end
 
             #: () -> Array[String]

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

@@ -31,6 +31,8 @@ module Roast
                   Messages::SystemMessage.new(type:, hash:)
                 when :text
                   Messages::TextMessage.new(type:, hash:)
+                when :thinking
+                  Messages::ThinkingMessage.new(type:, hash:)
                 when :tool_result
                   Messages::ToolResultMessage.new(type:, hash:)
                 when :tool_use
@@ -49,6 +51,9 @@ module Roast
             #: Symbol
             attr_reader :type
 
+            #: String?
+            attr_reader :error
+
             #: Hash[Symbol, untyped]
             attr_reader :unparsed
 
@@ -56,6 +61,7 @@ module Roast
             def initialize(type:, hash:)
               @session_id = hash.delete(:session_id)
               @type = type
+              @error = hash.delete(:error)
               hash.except!(*IGNORED_FIELDS)
               @unparsed = hash
             end

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

@@ -11,6 +11,7 @@ module Roast
               IGNORED_FIELDS = [
                 :duration_api_ms,
                 :permission_denials,
+                :stop_reason,
                 :usage,
                 :uuid,
               ].freeze

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

@@ -9,23 +9,27 @@ module Roast
           module Messages
             class SystemMessage < Message
               IGNORED_FIELDS = [
-                :subtype,
-                :cwd,
-                :tools,
-                :mcp_servers,
-                :permissionMode,
-                :slash_commands,
+                :agents,
                 :apiKeySource,
+                :compact_metadata,
                 :claude_code_version,
+                :cwd,
+                :exit_code,
+                :fast_mode_state,
+                :hook_event,
+                :hook_name,
+                :mcp_servers,
                 :output_style,
-                :agents,
-                :skills,
+                :permissionMode,
                 :plugins,
-                :hook_name,
-                :hook_event,
-                :stdout,
+                :skills,
+                :slash_commands,
+                # TODO: "status": "compacting" indicates compaction in progress. We might want to handle that someday
+                :status,
                 :stderr,
-                :exit_code,
+                :stdout,
+                :subtype,
+                :tools,
               ].freeze
 
               #: String?

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

@@ -0,0 +1,36 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module Cogs
+    class Agent < Cog
+      module Providers
+        class Claude < Provider
+          module Messages
+            class ThinkingMessage < Message
+              IGNORED_FIELDS = [
+                :signature,
+                :role,
+              ].freeze
+
+              #: String
+              attr_reader :thinking
+
+              #: (type: Symbol, hash: Hash[Symbol, untyped]) -> void
+              def initialize(type:, hash:)
+                @thinking = hash.delete(:thinking) || ""
+                hash.except!(*IGNORED_FIELDS)
+                super(type:, hash:)
+              end
+
+              #: (ClaudeInvocation::Context) -> String?
+              def format(context)
+                @thinking
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -9,6 +9,7 @@ module Roast
           module Messages
             class ToolUseMessage < Message
               IGNORED_FIELDS = [
+                :caller,
                 :role,
               ].freeze
 

data/lib/roast/event.rb

@@ -0,0 +1,75 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  class Event
+    class << self
+      #: (Hash[Symbol, untyped]) -> void
+      def <<(event)
+        EventMonitor.accept(Event.new(TaskContext.path, event))
+      end
+    end
+
+    LOG_TYPE_KEYS = [
+      :fatal,
+      :error,
+      :warn,
+      :info,
+      :debug,
+      :unknown,
+    ].freeze #: Array[Symbol]
+
+    OTHER_TYPE_KEYS = [
+      :begin,
+      :end,
+      :stdout,
+      :stderr,
+    ].freeze #: Array[Symbol]
+
+    #: Array[TaskContext::PathElement]
+    attr_reader :path
+
+    #: Hash[Symbol, untyped] :payload
+    attr_reader :payload
+
+    #: Time
+    attr_reader :time
+
+    delegate :[], :key?, :keys, to: :payload
+
+    #: (Array[TaskContext::PathElement] path, Hash[Symbol, untyped]) -> void
+    def initialize(path, payload)
+      @path = path
+      @payload = payload
+      @time = Time.now
+    end
+
+    #: () -> Symbol
+    def type
+      return :log if (LOG_TYPE_KEYS & @payload.keys).present?
+
+      (OTHER_TYPE_KEYS & @payload.keys).first || :unknown
+    end
+
+    #: () -> Integer
+    def log_severity
+      severity = case type
+      when :log
+        (LOG_TYPE_KEYS & @payload.keys).first || :unknown
+      when :stderr
+        :warn
+      else
+        :info
+      end
+      Logger::Severity.const_get(:LEVELS)[severity.to_s] # rubocop:disable Sorbet/ConstantsFromStrings
+    end
+
+    #: () -> String
+    def log_message
+      key = (LOG_TYPE_KEYS & @payload.keys).first
+      return "" unless key.present?
+
+      payload[key] || ""
+    end
+  end
+end

data/lib/roast/event_monitor.rb

@@ -0,0 +1,163 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module EventMonitor
+    extend self
+    include Kernel
+
+    class EventMonitorError < StandardError; end
+
+    class EventMonitorAlreadyStartedError < EventMonitorError; end
+
+    class EventMonitorNotRunningError < EventMonitorError; end
+
+    @queue = Async::Queue.new.tap(&:close) #: Async::Queue
+    @task = nil #: Async::Task?
+
+    #: () -> bool
+    def running?
+      !@queue.closed?
+    end
+
+    #: () -> Async::Task
+    def start!
+      raise EventMonitorAlreadyStartedError if running?
+
+      OutputRouter.enable!
+      @queue = Async::Queue.new
+      @task = Async(transient: true) do
+        OutputRouter.mark_as_output_fiber!
+        loop do
+          event = @queue.pop #: as Event?
+          break if event.nil?
+
+          handle_event(event)
+        end
+      end
+    end
+
+    #: () -> void
+    def stop!
+      raise EventMonitorNotRunningError unless running?
+
+      OutputRouter.disable!
+      @queue.close
+      @task&.wait
+      @task = nil
+    end
+
+    #: () -> void
+    def reset!
+      OutputRouter.disable!
+      @queue.close
+      @task = nil
+    end
+
+    #: (Event) -> void
+    def accept(event)
+      if running?
+        @queue.push(event)
+      else
+        handle_event(event)
+      end
+    end
+
+    private
+
+    #: (Event) -> void
+    def handle_event(event)
+      with_stubbed_class_method_returning(Time, :now, event.time) do
+        OutputRouter.mark_as_output_fiber!
+        handler_method_name = "handle_#{event.type}_event".to_sym
+        if respond_to?(handler_method_name, true)
+          send(handler_method_name, event)
+        else
+          handle_unknown_event(event)
+        end
+      end
+    end
+
+    #: (Event) -> void
+    def handle_begin_event(event)
+      # The first path element is always the top-level ExecutionManager
+      handle_begin_workflow_event(event) if event.path.length == 1
+      return unless event[:begin].cog.present?
+
+      Roast::Log.logger.info { "#{format_path(event)} Starting" }
+    end
+
+    def handle_begin_workflow_event(event)
+      execution_manager = event[:begin].execution_manager.not_nil!
+      workflow_context = execution_manager.workflow_context
+      Roast::Log.logger.info("🔥🔥🔥 Workflow Starting")
+      Roast::Log.logger.debug do
+        message = <<~MESSAGE
+          Workflow Context:
+            Targets: #{workflow_context.params.targets}
+            Args: #{workflow_context.params.args}
+            Kwargs: #{workflow_context.params.kwargs}
+            Temporary Directory: #{workflow_context.tmpdir}
+            Workflow Directory: #{workflow_context.workflow_dir}
+            Working Directory: #{Dir.pwd}
+        MESSAGE
+        message.strip
+      end
+    end
+
+    #: (Event) -> void
+    def handle_end_event(event)
+      # The first path element is always the top-level ExecutionManager
+      Roast::Log.logger.info("🔥🔥🔥 Workflow Complete") if event.path.length == 1
+      return unless event[:end].cog.present?
+
+      Roast::Log.logger.info { "#{format_path(event)} Complete" }
+    end
+
+    #: (Event) -> void
+    def handle_log_event(event)
+      Roast::Log.logger.add(event.log_severity, event.log_message)
+    end
+
+    #: (Event) -> void
+    def handle_stderr_event(event)
+      Roast::Log.logger.warn { "#{format_path(event)} ❯❯ #{event[:stderr]}" }
+    end
+
+    #: (Event) -> void
+    def handle_stdout_event(event)
+      Roast::Log.logger.info { "#{format_path(event)} ❯ #{event[:stdout]}" }
+    end
+
+    #: (Event) -> void
+    def handle_unknown_event(event)
+      Roast::Log.logger.unknown(event.inspect)
+    end
+
+    #: (Event) -> String
+    def format_path(event)
+      event.path.map do |element|
+        cog = element.cog
+        execution_manager = element.execution_manager
+        if cog.present?
+          "#{cog.type}#{cog.anonymous? ? "" : "(:#{cog.name})"}"
+        elsif execution_manager&.scope
+          "{:#{execution_manager.scope}}[#{execution_manager.scope_index}]"
+        end
+      end.compact.join(" -> ")
+    end
+
+    #: [T] (Class, Symbol, untyped) { () -> T } -> T
+    def with_stubbed_class_method_returning(klass, method_name, return_value, &blk)
+      original_method = klass.singleton_class.instance_method(method_name)
+      klass.singleton_class.silence_redefinition_of_method(method_name)
+      klass.define_singleton_method(method_name, proc { return_value })
+      blk.call
+    ensure
+      if original_method
+        klass.singleton_class.silence_redefinition_of_method(method_name)
+        klass.define_singleton_method(method_name, original_method)
+      end
+    end
+  end
+end

data/lib/roast/execution_manager.rb

@@ -24,6 +24,18 @@ module Roast
 
     class OutputsAlreadyDefinedError < ExecutionManagerError; end
 
+    #: WorkflowContext
+    attr_reader :workflow_context
+
+    #: Symbol?
+    attr_reader :scope
+
+    #: untyped
+    attr_reader :scope_value
+
+    #: Integer
+    attr_reader :scope_index
+
     #: untyped
     attr_reader :final_output
 
@@ -79,6 +91,7 @@ module Roast
       @running = true
       Sync do |sync_task|
         sync_task.annotate("ExecutionManager #{@scope}")
+        TaskContext.begin_execution_manager(self)
         @cog_stack.each do |cog|
           cog_config = @config_manager.config_for(cog.class, cog.name)
           cog_task = cog.run!(
@@ -97,6 +110,7 @@ module Roast
       ensure
         @barrier.stop
         compute_final_output
+        TaskContext.end
         @running = false
       end
     end
@@ -199,8 +213,14 @@ module Roast
           raise NotImplementedError, "No system cog manager defined for #{cog_class}"
         end
       else
-        cog_name = Array.wrap(cog_args).shift || Cog.generate_fallback_name
-        cog_instance = cog_class.new(cog_name, cog_input_proc)
+        cog_name = Array.wrap(cog_args).shift
+        if cog_name
+          anonymous = false
+        else
+          anonymous = true
+          cog_name = Cog.generate_fallback_name
+        end
+        cog_instance = cog_class.new(cog_name, cog_input_proc, anonymous:)
       end
       add_cog_instance(cog_instance)
     end

data/lib/roast/log.rb

@@ -4,8 +4,9 @@
 module Roast
   # Central logging interface for Roast.
   #
-  # Provides a simple, testable logging API that wraps the standard library Logger.
-  # Outputs to $stderr by default.
+  # Provides a simple, testable logging API that wraps the standard library Logger
+  # and leverages Roast's Event framework for clean async task integration with proper task hierarchy attribution.
+  # Outputs to STDERR by default.
   #
   # @example Basic usage
   #   Roast::Log.info("Processing file...")
@@ -17,61 +18,83 @@ module Roast
   #   Roast::Log.logger = Rails.logger
   #
   module Log
+    extend self
+    include Kernel
+
     LOG_LEVELS = {
-      "DEBUG" => ::Logger::DEBUG,
-      "INFO" => ::Logger::INFO,
-      "WARN" => ::Logger::WARN,
-      "ERROR" => ::Logger::ERROR,
-      "FATAL" => ::Logger::FATAL,
-    }.freeze
-
-    class << self
-      attr_writer :logger
-
-      def debug(message)
-        logger.debug(message)
-      end
+      DEBUG: ::Logger::DEBUG,
+      INFO: ::Logger::INFO,
+      WARN: ::Logger::WARN,
+      ERROR: ::Logger::ERROR,
+      FATAL: ::Logger::FATAL,
+    }.freeze #: Hash[Symbol, Integer]
 
-      def info(message)
-        logger.info(message)
-      end
+    attr_writer :logger
 
-      def warn(message)
-        logger.warn(message)
-      end
+    #: (String) -> void
+    def debug(message)
+      Roast::Event << { debug: message }
+    end
 
-      def error(message)
-        logger.error(message)
-      end
+    #: (String) -> void
+    def info(message)
+      Roast::Event << { info: message }
+    end
 
-      def fatal(message)
-        logger.fatal(message)
-      end
+    #: (String) -> void
+    def warn(message)
+      Roast::Event << { warn: message }
+    end
 
-      def logger
-        @logger ||= create_logger
-      end
+    #: (String) -> void
+    def error(message)
+      Roast::Event << { error: message }
+    end
 
-      def reset!
-        @logger = nil
-      end
+    #: (String) -> void
+    def fatal(message)
+      Roast::Event << { fatal: message }
+    end
 
-      private
+    #: (String) -> void
+    def unknown(message)
+      Roast::Event << { unknown: message }
+    end
 
-      def create_logger
-        ::Logger.new($stderr, progname: "roast").tap do |l|
-          l.level = LOG_LEVELS.fetch(log_level)
-        end
-      end
+    #: () -> Logger
+    def logger
+      @logger ||= create_logger
+    end
+
+    #: () -> void
+    def reset!
+      @logger = nil
+    end
 
-      def log_level
-        level_str = (ENV["ROAST_LOG_LEVEL"] || "INFO").upcase
-        unless LOG_LEVELS.key?(level_str)
-          raise ArgumentError, "Invalid log level: #{level_str}. Valid levels are: #{LOG_LEVELS.keys.join(", ")}"
-        end
+    #: () -> bool
+    def tty?
+      return false unless @logger
 
-        level_str
+      logdev = @logger.instance_variable_get(:@logdev)&.dev
+      logdev&.respond_to?(:isatty) && logdev&.isatty
+    end
+
+    private
+
+    #: () -> Logger
+    def create_logger
+      ::Logger.new($stderr, progname: "Roast").tap do |l|
+        l.level = LOG_LEVELS.fetch(log_level("INFO"))
+        l.formatter = Roast::LogFormatter.new(tty: $stderr.tty?)
       end
     end
+
+    #: (String) -> Symbol
+    def log_level(default_level)
+      level = (ENV["ROAST_LOG_LEVEL"] || default_level).upcase.to_sym
+      raise ArgumentError, "Invalid log level: #{level}. Valid levels are: #{LOG_LEVELS.keys.join(", ")}" unless LOG_LEVELS.key?(level)
+
+      level
+    end
   end
 end

data/lib/roast/log_formatter.rb

@@ -0,0 +1,56 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  class LogFormatter < ::Logger::Formatter
+    TTY_FORMAT = "• %.1s, %s\n" #: String
+    NON_TTY_FORMAT = "%.1s, [%s] %5s -- %s\n" #: String
+    DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%6N" #: String
+
+    #: (tty: bool) -> void
+    def initialize(tty:)
+      super()
+      @tty = tty
+      @rainbow = Rainbow.new.tap { |r| r.enabled = tty }
+    end
+
+    def call(severity, time, _progname, msg)
+      line = if @tty
+        format(TTY_FORMAT, severity, msg2str(msg))
+      else
+        format(NON_TTY_FORMAT, severity, time.strftime(DATETIME_FORMAT), severity, msg2str(msg))
+      end
+      colourize(severity, line)
+    end
+
+    private
+
+    #: (String, String) -> String
+    def colourize(severity, line)
+      if line.include?("❯❯") # standard error lines
+        @rainbow.wrap(line).yellow
+      elsif line.include?("❯") # standard output lines
+        @rainbow.wrap(line)
+      else
+        case severity
+        when "ERROR", "FATAL" then @rainbow.wrap(line).red
+        when "WARN" then @rainbow.wrap(line).color("#FF8C00") # orange
+        when "INFO" then @rainbow.wrap(line).bright
+        when "DEBUG" then @rainbow.wrap(line).faint
+        else line
+        end
+      end
+    end
+
+    #: (String | Exception | untyped) -> String
+    def msg2str(msg)
+      msg = case msg
+      when ::String
+        msg.strip
+      else
+        msg
+      end
+      super(msg)
+    end
+  end
+end

data/lib/roast/output_router.rb

@@ -0,0 +1,76 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  class OutputRouter
+    # This is the name of the alias methods for `:write` on the $stdout and $stderr objects
+    # that bypass OutputRouter's wrapper. Calling this method will write to those output stream directly.
+    WRITE_WITHOUT_ROAST = :write_without_roast
+
+    class << self
+      #: () -> bool
+      def enable!
+        return false if enabled?
+
+        activate($stdout, :stdout)
+        activate($stderr, :stderr)
+        mark_as_output_fiber!
+        true
+      end
+
+      #: () -> bool
+      def disable!
+        return false unless enabled?
+
+        deactivate($stdout)
+        deactivate($stderr)
+        @output_fiber = nil
+        true
+      end
+
+      #: () -> bool
+      def enabled?
+        $stdout.respond_to?(WRITE_WITHOUT_ROAST)
+      end
+
+      #: () -> bool
+      def output_fiber?
+        @output_fiber == Fiber.current
+      end
+
+      #: () -> void
+      def mark_as_output_fiber!
+        @output_fiber = Fiber.current
+      end
+
+      private
+
+      #: (IO stream, Symbol name) -> void
+      def activate(stream, name)
+        router = self
+        stream.singleton_class.send(:alias_method, WRITE_WITHOUT_ROAST, :write)
+        stream.define_singleton_method(:write) do |*args|
+          if router.output_fiber?
+            self #: as untyped # rubocop:disable Style/RedundantSelf
+              .send(WRITE_WITHOUT_ROAST, *args)
+          else
+            str = args.map(&:to_s).join
+            Event << case name
+            when :stdout then { stdout: str }
+            when :stderr then { stderr: str }
+            else { unknown: str }
+            end
+          end
+        end
+      end
+
+      #: (IO stream) -> void
+      def deactivate(stream)
+        sc = stream.singleton_class
+        sc.send(:remove_method, :write)
+        sc.send(:alias_method, :write, WRITE_WITHOUT_ROAST)
+        sc.send(:remove_method, WRITE_WITHOUT_ROAST)
+      end
+    end
+  end
+end

data/lib/roast/system_cog/params.rb

@@ -23,8 +23,16 @@ module Roast
       #
       #: (Symbol?) -> void
       def initialize(name)
+        @anonymous = name.nil? #: bool
         @name = name || Cog.generate_fallback_name
       end
+
+      # Whether the cog is using a fallback name, or was given one explicitly.
+      #
+      #: () -> bool
+      def anonymous?
+        @anonymous
+      end
     end
   end
 end

data/lib/roast/system_cog.rb

@@ -18,9 +18,9 @@ module Roast
       end
     end
 
-    #: (Symbol, ^(Cog::Input) -> untyped) { (Cog::Input, Cog::Config) -> Cog::Output } -> void
-    def initialize(name, cog_input_proc, &on_execute)
-      super(name, cog_input_proc)
+    #: (Symbol, ^(Cog::Input) -> untyped, anonymous: bool) { (Cog::Input, Cog::Config) -> Cog::Output } -> void
+    def initialize(name, cog_input_proc, anonymous:, &on_execute)
+      super(name, cog_input_proc, anonymous:)
       @on_execute = on_execute
     end
 

data/lib/roast/system_cogs/call.rb

@@ -89,7 +89,7 @@ module Roast
 
         #: (Params, ^(Cog::Input) -> untyped) -> SystemCogs::Call
         def create_call_system_cog(params, input_proc)
-          SystemCogs::Call.new(params.name, input_proc) do |input|
+          SystemCogs::Call.new(params.name, input_proc, anonymous: params.anonymous?) do |input|
             input = input #: as Input
             raise ExecutionManager::ExecutionScopeNotSpecifiedError unless params.run.present?
 

data/lib/roast/system_cogs/map.rb

@@ -257,7 +257,7 @@ module Roast
 
         #: (Params, ^(Cog::Input) -> untyped) -> SystemCogs::Map
         def create_map_system_cog(params, input_proc)
-          SystemCogs::Map.new(params.name, input_proc) do |input, config|
+          SystemCogs::Map.new(params.name, input_proc, anonymous: params.anonymous?) do |input, config|
             raise ExecutionManager::ExecutionScopeNotSpecifiedError unless params.run.present?
 
             input = input #: as Input

data/lib/roast/system_cogs/repeat.rb

@@ -206,7 +206,7 @@ module Roast
 
         #: (Params, ^(Cog::Input) -> untyped) -> SystemCogs::Repeat
         def create_repeat_system_cog(params, input_proc)
-          SystemCogs::Repeat.new(params.name, input_proc) do |input|
+          SystemCogs::Repeat.new(params.name, input_proc, anonymous: params.anonymous?) do |input|
             input = input #: as Input
             raise ExecutionManager::ExecutionScopeNotSpecifiedError unless params.run.present?
 

data/lib/roast/task_context.rb

@@ -0,0 +1,53 @@
+# typed: true
+# frozen_string_literal: true
+
+module Roast
+  module TaskContext
+    extend self
+
+    class PathElement
+      #: Cog?
+      attr_reader :cog
+
+      #: ExecutionManager?
+      attr_reader :execution_manager
+
+      #: (?cog: Cog?, ?execution_manager: ExecutionManager?) -> void
+      def initialize(cog: nil, execution_manager: nil)
+        @cog = cog
+        @execution_manager = execution_manager
+      end
+    end
+
+    #: () -> Array[PathElement]
+    def path
+      Fiber[:path]&.deep_dup || []
+    end
+
+    #: (Cog) -> Array[PathElement]
+    def begin_cog(cog)
+      begin_element(PathElement.new(cog:))
+    end
+
+    #: (ExecutionManager) -> Array[PathElement]
+    def begin_execution_manager(execution_manager)
+      begin_element(PathElement.new(execution_manager:))
+    end
+
+    #: () -> [PathElement, Array[PathElement]]
+    def end
+      Event << { end: Fiber[:path]&.last }
+      el = Fiber[:path]&.pop
+      [el, path]
+    end
+
+    private
+
+    #: (PathElement) -> Array[PathElement]
+    def begin_element(element)
+      Fiber[:path] = (Fiber[:path] || []) + [element]
+      Event << { begin: element }
+      path
+    end
+  end
+end

data/lib/roast/version.rb

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

data/lib/roast/workflow.rb

@@ -4,20 +4,28 @@
 module Roast
   class Workflow
     class WorkflowError < Roast::Error; end
+
     class WorkflowNotPreparedError < WorkflowError; end
+
     class WorkflowAlreadyPreparedError < WorkflowError; end
+
     class WorkflowAlreadyStartedError < WorkflowError; end
+
     class InvalidLoadableReference < WorkflowError; end
 
     class << self
       #: (String | Pathname, WorkflowParams) -> void
       def from_file(workflow_path, params)
-        Dir.mktmpdir("roast-") do |tmpdir|
-          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!
+        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!
+          end
         end
       end
     end

data/lib/roast.rb

@@ -2,8 +2,8 @@
 # frozen_string_literal: true
 
 # Standard library requires
-require "digest"
 require "English"
+require "digest"
 require "erb"
 require "fileutils"
 require "json"
@@ -24,14 +24,15 @@ require "active_support"
 require "active_support/cache"
 require "active_support/core_ext/array"
 require "active_support/core_ext/hash"
-require "active_support/core_ext/object/deep_dup"
 require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/object/deep_dup"
 require "active_support/core_ext/string"
 require "active_support/core_ext/string/inflections"
 require "active_support/isolated_execution_state"
 require "active_support/notifications"
 require "async"
 require "async/semaphore"
+require "rainbow"
 require "ruby_llm"
 
 # Require project components that will not get automatically loaded

data/roast-ai.gemspec

@@ -33,6 +33,7 @@ Gem::Specification.new do |spec|
 
   spec.add_dependency("activesupport", "~> 8.0")
   spec.add_dependency("async", ">= 2.34")
+  spec.add_dependency("rainbow", ">= 3.0.0")
   spec.add_dependency("ruby_llm", ">= 1.8")
   spec.add_dependency("zeitwerk", ">= 2.6")
 end

data/sorbet/tapioca/require.rb

@@ -6,8 +6,8 @@ require "active_support"
 require "active_support/cache"
 require "active_support/core_ext/array"
 require "active_support/core_ext/hash"
-require "active_support/core_ext/object/deep_dup"
 require "active_support/core_ext/module/delegation"
+require "active_support/core_ext/object/deep_dup"
 require "active_support/core_ext/string"
 require "active_support/core_ext/string/inflections"
 require "active_support/isolated_execution_state"
@@ -17,8 +17,9 @@ require "async/semaphore"
 require "bundler/setup"
 require "json"
 require "open3"
+require "optparse"
+require "rainbow"
 require "shellwords"
 require "sqlite3"
-require "optparse"
 require "timeout"
 require "zeitwerk"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: roast-ai
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Shopify
@@ -37,6 +37,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.34'
+- !ruby/object:Gem::Dependency
+  name: rainbow
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: ruby_llm
   requirement: !ruby/object:Gem::Requirement
@@ -107,6 +121,8 @@ files:
 - examples/async_cogs_complex.rb
 - examples/call.rb
 - examples/collect_from.rb
+- examples/console_output.rb
+- examples/custom_logging.rb
 - examples/demo/Gemfile
 - examples/demo/Gemfile.lock
 - examples/demo/cogs/local.rb
@@ -133,6 +149,7 @@ files:
 - examples/prototype.rb
 - examples/repeat_loop_results.rb
 - examples/ruby_cog.rb
+- examples/shell_sanitization.rb
 - examples/simple_agent.rb
 - examples/simple_chat.rb
 - examples/simple_repeat.rb
@@ -171,6 +188,7 @@ files:
 - lib/roast/cogs/agent/providers/claude/messages/result_message.rb
 - lib/roast/cogs/agent/providers/claude/messages/system_message.rb
 - lib/roast/cogs/agent/providers/claude/messages/text_message.rb
+- lib/roast/cogs/agent/providers/claude/messages/thinking_message.rb
 - lib/roast/cogs/agent/providers/claude/messages/tool_result_message.rb
 - lib/roast/cogs/agent/providers/claude/messages/tool_use_message.rb
 - lib/roast/cogs/agent/providers/claude/messages/unknown_message.rb
@@ -191,15 +209,20 @@ files:
 - lib/roast/config_manager.rb
 - lib/roast/control_flow.rb
 - lib/roast/error.rb
+- lib/roast/event.rb
+- lib/roast/event_monitor.rb
 - lib/roast/execution_context.rb
 - lib/roast/execution_manager.rb
 - lib/roast/log.rb
+- lib/roast/log_formatter.rb
 - lib/roast/nil_assertions.rb
+- lib/roast/output_router.rb
 - lib/roast/system_cog.rb
 - lib/roast/system_cog/params.rb
 - lib/roast/system_cogs/call.rb
 - lib/roast/system_cogs/map.rb
 - lib/roast/system_cogs/repeat.rb
+- lib/roast/task_context.rb
 - lib/roast/version.rb
 - lib/roast/workflow.rb
 - lib/roast/workflow_context.rb