roast-ai 1.2.0 → 1.4.0

data/lib/roast/cogs/agent/providers/pi/messages/tool_call_message.rb

@@ -25,31 +25,231 @@ module Roast
               def initialize(id:, name:, arguments:)
                 @id = id
                 @name = name
-                @arguments = arguments
+                @arguments = arguments.is_a?(Hash) ? arguments : {}
               end
 
               #: () -> String?
               def format
                 return unless name
 
-                case name.to_s.downcase
-                when "bash"
-                  "BASH #{arguments[:command]}"
-                when "read"
-                  "READ #{arguments[:path]}"
-                when "edit"
-                  "EDIT #{arguments[:path]}"
-                when "write"
-                  "WRITE #{arguments[:path]}"
-                when "grep"
-                  "GREP #{arguments[:pattern]} #{arguments[:path]}"
-                when "find"
-                  "FIND #{arguments[:pattern]} #{arguments[:path]}"
-                when "ls"
-                  "LS #{arguments[:path]}"
-                else
-                  "TOOL [#{name}] #{arguments.inspect}"
+                format_method_name = "format_#{name.to_s.downcase}".to_sym
+                return send(format_method_name) if respond_to?(format_method_name, true)
+
+                format_unknown
+              rescue StandardError
+                format_unknown
+              end
+
+              # Truncates each value in a formatted tool-call string to keep terminal output concise.
+              TRUNCATE_LIMIT = 45
+
+              private
+
+              # Formats a bash tool call.
+              #
+              # Input fields:
+              #   :command (String) – shell command to execute   [required]
+              #
+              # Output: "BASH <command>", with :command truncated to TRUNCATE_LIMIT
+              # chars. A missing command renders the bare "BASH".
+              #
+              # Examples:
+              #   BASH ls -la
+              #   BASH
+              #
+              #: () -> String
+              def format_bash
+                command = truncate(arguments[:command])
+                command.empty? ? "BASH" : "BASH #{command}"
+              end
+
+              # Formats a read tool call.
+              #
+              # Input fields:
+              #   :path   (String)  – file to read              [required]
+              #   :offset (Integer) – 1-indexed first line       [optional]
+              #   :limit  (Integer) – maximum number of lines    [optional]
+              #
+              # Output: "READ <path>", with a line range appended when :offset and/or
+              # :limit is given:
+              #   :limit >= 1  → " (lines <start>–<end>)", start = :offset (default 1),
+              #                  end = start + :limit - 1
+              #   :offset only → " (from line <offset>)" (reads to end of file); also the
+              #                  fallback when :limit <= 0, which has no sensible range
+              # With neither, the bare "READ <path>". A missing path renders "READ".
+              #
+              # Examples:
+              #   READ lib/roast.rb (lines 30–80)
+              #   READ lib/roast.rb (from line 30)
+              #   READ lib/roast.rb
+              #
+              #: () -> String
+              def format_read
+                path, offset, limit = arguments.values_at(:path, :offset, :limit)
+                path = path.to_s
+                details = if limit&.positive?
+                  offset ||= 1
+                  "lines #{offset}–#{offset + limit - 1}"
+                elsif offset
+                  "from line #{offset}"
                 end
+                label = path.empty? ? "READ" : "READ #{path}"
+                details ? "#{label} (#{details})" : label
+              end
+
+              # Formats a write tool call.
+              #
+              # Input fields:
+              #   :path    (String) – file to write   [required]
+              #   :content (String) – file contents   [required]
+              #
+              # Output: 'WRITE <path> "<preview>" (+<n> <line|lines>)' – <preview> is the
+              # first line of :content (stripped, truncated to TRUNCATE_LIMIT chars) and
+              # <n> the number of lines written. The content summary is appended only
+              # when :content is present; a missing path renders the bare "WRITE".
+              #
+              # Examples:
+              #   WRITE lib/roast.rb "class Roast" (+10 lines)
+              #   WRITE config/app.yml "enabled: true" (+1 line)
+              #   WRITE lib/roast.rb
+              #   WRITE
+              #
+              #: () -> String
+              def format_write
+                path, content = arguments.values_at(:path, :content)
+                path = path.to_s
+                label = path.empty? ? "WRITE" : "WRITE #{path}"
+                return label if content.nil?
+
+                lines = content.to_s.lines
+                preview = truncate(lines.first.to_s.strip)
+                count = lines.length
+                "#{label} \"#{preview}\" (+#{count} #{"line".pluralize(count)})"
+              end
+
+              # Formats an edit tool call.
+              #
+              # Input fields:
+              #   :path  (String) – file to edit                          [required]
+              #   :edits (Array)  – edit blocks, each {oldText, newText}   [required]
+              #
+              # Output: "EDIT <path> (<n> <edit|edits>)" – <n> is the number of edit
+              # blocks applied in the call. The count is always shown.
+              #
+              # Examples:
+              #   EDIT lib/roast.rb (1 edit)
+              #   EDIT config/app.yml (3 edits)
+              #
+              #: () -> String
+              def format_edit
+                path = arguments[:path]
+                edits = arguments[:edits] || []
+                count = edits.length
+                "EDIT #{path} (#{count} #{"edit".pluralize(count)})"
+              end
+
+              # Formats a grep tool call.
+              #
+              # Input fields:
+              #   :pattern (String)  – regex/text to search for      [required]
+              #   :path    (String)  – file or directory to search   [optional]
+              #   :glob    (String)  – glob filter for matched files [optional]
+              #   :limit   (Integer) – max number of matches         [optional]
+              #
+              # Output: 'GREP "<pattern>" <path> (glob: <glob>, limit: <limit>)' –
+              # <pattern> is truncated to TRUNCATE_LIMIT chars; <path> is shown only
+              # when present. The "glob:" and "limit:" details are each included only
+              # when present and joined with ", " inside a single trailing "(...)".
+              # `path`, `glob` and `limit` are left untruncated as they are usually short and
+              # contain important information that we don't want to truncate.
+              #
+              # Examples:
+              #   GREP "def format" lib (glob: *.rb, limit: 50)
+              #   GREP "TODO" (limit: 50)
+              #   GREP "TODO"
+              #
+              #: () -> String
+              def format_grep
+                pattern, path, glob, limit = arguments.values_at(:pattern, :path, :glob, :limit)
+                base = "GREP \"#{truncate(pattern)}\""
+                base = "#{base} #{path}" if path.present?
+                details = [
+                  ("glob: #{glob}" if glob.present?),
+                  ("limit: #{limit}" if limit.present?),
+                ].compact
+                details.any? ? "#{base} (#{details.join(", ")})" : base
+              end
+
+              # Formats a find tool call.
+              #
+              # Input fields:
+              #   :pattern (String)  – filename glob to match   [required]
+              #   :path    (String)  – directory to search in   [optional]
+              #   :limit   (Integer) – max number of results    [optional]
+              #
+              # Output: "FIND <pattern> (path: <path>, limit: <limit>)" – the "path:"
+              # and "limit:" details are each included only when present and joined
+              # with ", " inside a single trailing "(...)".
+              #
+              # Examples:
+              #   FIND *.rb (path: lib, limit: 50)
+              #   FIND *.rb (limit: 50)
+              #   FIND *.rb
+              #
+              #: () -> String
+              def format_find
+                pattern, path, limit = arguments.values_at(:pattern, :path, :limit)
+                details = [
+                  ("path: #{path}" if path.present?),
+                  ("limit: #{limit}" if limit.present?),
+                ].compact
+                details.any? ? "FIND #{pattern} (#{details.join(", ")})" : "FIND #{pattern}"
+              end
+
+              # Formats an ls tool call.
+              #
+              # Input fields:
+              #   :path (String) – directory to list   [optional]
+              #
+              # Output: "LS <path>" – a missing path renders the bare "LS".
+              #
+              # Examples:
+              #   LS lib/roast
+              #   LS
+              #
+              #: () -> String
+              def format_ls
+                path = arguments[:path]
+                path.to_s.empty? ? "LS" : "LS #{path}"
+              end
+
+              # Formats a tool call for which Roast has no dedicated formatter.
+              #
+              # Output: "<NAME> <key>: <value>, ..." – the upcased tool name, then each
+              # argument as "<key>: <inspected value>", ordered shortest pair first so the
+              # most compact arguments stay visible, joined with ", ". Every value is
+              # truncated to TRUNCATE_LIMIT chars so one large argument can't flood the
+              # line; keys are always shown. No arguments renders the bare "<NAME>".
+              #
+              # Examples:
+              #   WEB_SEARCH max_results: 5, query: "ruby pluralize"
+              #   DEPLOY
+              #
+              #: () -> String
+              def format_unknown
+                label = name.to_s.upcase
+                return label if arguments.empty?
+
+                details = arguments.map { |key, value| "#{key}: #{truncate(value.inspect)}" }.sort_by { |s| [s.length, s] }.join(", ")
+                "#{label} #{details}"
+              end
+
+              # Truncates to TRUNCATE_LIMIT chars, appending "..." when cut. nil -> "".
+              #
+              #: (String?) -> String
+              def truncate(str)
+                s = str.to_s
+                s.length > TRUNCATE_LIMIT ? "#{s[0...TRUNCATE_LIMIT - 3]}..." : s
               end
             end
           end

data/lib/roast/cogs/agent/providers/pi/messages/tool_result_message.rb

@@ -30,23 +30,218 @@ module Roast
                 @tool_name = tool_name
                 @content = content
                 @is_error = is_error
+                @name = (tool_name || "unknown").to_s #: String
+                @input = {} #: Hash[Symbol, untyped]
               end
 
               #: (PiInvocation::Context) -> String?
               def format(context)
-                tool_call = context.tool_call(tool_call_id)
-                name = tool_name || tool_call&.name || "unknown"
-                status = is_error ? "ERROR" : "OK"
-
-                # Truncate long tool results for progress display
-                c = content
-                display_content = if c && c.length > 200
-                  "#{c[0..197]}..."
-                else
-                  c
-                end
-
-                "#{name.upcase} #{status}#{display_content ? " #{display_content}" : ""}"
+                call = context.tool_call(tool_call_id)
+                @name = (tool_name || call&.name || "unknown").to_s
+                @input = call&.arguments || {}
+
+                return error_line if is_error
+
+                format_method_name = "format_#{@name.downcase}".to_sym
+                return send(format_method_name) if respond_to?(format_method_name, true)
+
+                format_unknown
+              rescue StandardError
+                format_unknown
+              end
+
+              # Truncates each element in a formatted tool-result string to keep terminal output concise.
+              TRUNCATE_LIMIT = 45
+
+              private
+
+              # Formats a bash tool result.
+              #
+              # Content: the command's output text.
+              #
+              # Output: "BASH OK <n> <line|lines> · <preview>" – <n> is the line count
+              # (pluralized) and <preview> is the first line, stripped and truncated to
+              # TRUNCATE_LIMIT chars. The preview is omitted when there is no output.
+              #
+              # Examples:
+              #   BASH OK 12 lines · Cloning into 'roast'...
+              #   BASH OK 1 line · hello world
+              #   BASH OK 0 lines
+              #
+              #: () -> String
+              def format_bash
+                lines = content.to_s.lines
+                count = lines.length
+                preview = truncate(lines.first.to_s.strip)
+                ok_line("#{count} #{"line".pluralize(count)}", preview)
+              end
+
+              # Formats a read tool result.
+              #
+              # Content: the file's text.
+              #
+              # Output: "READ OK <n> <line|lines>" – <n> is the file's line count
+              # (pluralized). Blank lines are counted: this is the file's own length, so
+              # it deliberately differs from entry-listing tools (find/ls), which drop
+              # blanks because a blank isn't an entry.
+              #
+              # Examples:
+              #   READ OK 42 lines
+              #   READ OK 1 line
+              #   READ OK 0 lines
+              #
+              #: () -> String
+              def format_read
+                count = content.to_s.lines.length
+                ok_line("#{count} #{"line".pluralize(count)}")
+              end
+
+              # Formats a write tool result.
+              #
+              # Input: :path – the path that was written, from the originating call.
+              #
+              # Output: "WRITE OK <path>" – the file path, omitted when the call
+              # had none.
+              #
+              # Examples:
+              #   WRITE OK lib/roast/version.rb
+              #   WRITE OK
+              #
+              #: () -> String
+              def format_write
+                ok_line(@input[:path])
+              end
+
+              # Formats an edit tool result.
+              #
+              # Input: :path – the path that was edited, from the originating call.
+              #
+              # Output: "EDIT OK <path>" – the file path, omitted when the call
+              # had none.
+              #
+              # Examples:
+              #   EDIT OK lib/roast/version.rb
+              #   EDIT OK
+              #
+              #: () -> String
+              def format_edit
+                ok_line(@input[:path])
+              end
+
+              # Formats a grep tool result.
+              #
+              # Content: matching lines, and possibly informational notes, one per
+              # line.
+              #
+              # Output: "GREP OK <n> <match|matches>[ · NOTE <notes>]" – <n> counts
+              # lines that look like matches (a leading path or line-number prefix);
+              # any remaining lines are joined into a truncated NOTE, shown only when
+              # there are both matches and notes.
+              #
+              # Examples:
+              #   GREP OK 3 matches
+              #   GREP OK 1 match
+              #   GREP OK 0 matches
+              #
+              #: () -> String
+              def format_grep
+                lines = content.to_s.lines.map(&:strip).reject(&:empty?)
+                matches, notes = lines.partition { |line| line.match?(%r{\A\S+/}) || line.match?(/\A(?:\S+:)?\d+:/) }
+                count = matches.length
+                note = "NOTE #{truncate(notes.join(" "))}" if matches.any? && notes.any?
+                ok_line("#{count} #{"match".pluralize(count)}", note)
+              end
+
+              # Formats a find tool result.
+              #
+              # Content: matching paths, one per line, plus an optional status line –
+              # either a bracketed notice ("[2 results limit reached. ...]") or the
+              # no-results prose ("No files found matching pattern").
+              #
+              # Output: "FIND OK <n> <path|paths>[ · NOTE <status>]" – <n> counts the
+              # path lines only, and the notice's brackets are dropped. As in #format_grep,
+              # the NOTE is shown only alongside results: "0 paths" already says what the
+              # no-results prose would.
+              #
+              # Examples:
+              #   FIND OK 12 paths
+              #   FIND OK 1 path
+              #   FIND OK 2 paths · NOTE 2 results limit reached. Use limit=4 for m...
+              #   FIND OK 0 paths
+              #
+              #: () -> String
+              def format_find
+                lines = content.to_s.lines.map(&:strip).reject(&:empty?)
+                notes, paths = lines.partition { |line| line.sub!(/\A\[(.*)\]\z/, '\1') || line.match?(/\ANo files found/) }
+                count = paths.length
+                note = "NOTE #{truncate(notes.join(" "))}" if paths.any? && notes.any?
+                ok_line("#{count} #{"path".pluralize(count)}", note)
+              end
+
+              # Formats an ls tool result.
+              #
+              # Content: directory entries, one per line.
+              #
+              # Output: "LS OK <n> <entry|entries>" – <n> is the number of non-blank
+              # lines (pluralized).
+              #
+              # Examples:
+              #   LS OK 8 entries
+              #   LS OK 1 entry
+              #   LS OK 0 entries
+              #
+              #: () -> String
+              def format_ls
+                count = content.to_s.lines.map(&:strip).reject(&:empty?).length
+                ok_line("#{count} #{"entry".pluralize(count)}")
+              end
+
+              # Formats a result for which Roast has no dedicated formatter.
+              #
+              # Content: the tool's output text.
+              #
+              # Output: "<NAME> OK <preview>" – the first line of content, stripped and
+              # truncated to TRUNCATE_LIMIT chars. The preview is omitted when there is
+              # no content.
+              #
+              # Examples:
+              #   WEB_SEARCH OK 3 results for "ruby pluralize"
+              #   DEPLOY OK
+              #
+              #: () -> String
+              def format_unknown
+                preview = truncate(content.to_s.lines.first.to_s.strip)
+                ok_line(preview)
+              end
+
+              # Renders "<TOOL> OK[ <part> · <part> · ...]"; the success-side twin of
+              # #error_line. Blank/nil parts are dropped and the rest joined with " · ",
+              # so callers pass each piece of the summary without minding separators.
+              #
+              #: (*String?) -> String
+              def ok_line(*parts)
+                summary = parts.select(&:present?).join(" · ")
+                prefix = "#{@name.upcase} OK"
+                summary.present? ? "#{prefix} #{summary}" : prefix
+              end
+
+              # Renders "<TOOL> ERROR <message>". The content is shown as-is and intentionally not truncated,
+              # preserving the full diagnostic.
+              #
+              # Examples:
+              #   READ ERROR ENOENT: no such file or directory
+              #
+              #: () -> String
+              def error_line
+                "#{@name.upcase} ERROR #{content.to_s.strip}".strip
+              end
+
+              # Truncates to TRUNCATE_LIMIT chars, appending "..." when cut. nil -> "".
+              #
+              #: (String?) -> String
+              def truncate(str)
+                s = str.to_s
+                s.length > TRUNCATE_LIMIT ? "#{s[0...TRUNCATE_LIMIT - 3]}..." : s
               end
             end
           end

data/lib/roast/cogs/agent/providers/pi/pi_invocation.rb

@@ -60,6 +60,7 @@ module Roast
               @append_system_prompt = config.valid_append_system_prompt #: String?
               @replace_system_prompt = config.valid_replace_system_prompt #: String?
               @working_directory = config.valid_working_directory #: Pathname?
+              @timeout = config.valid_timeout #: Integer?
               @prompt = prompt #: String
               @session = session #: String?
               @context = Context.new #: Context
@@ -86,6 +87,7 @@ module Roast
                 command_line,
                 working_directory: @working_directory,
                 stdin_content: @prompt,
+                timeout: @timeout,
                 stdout_handler: lambda { |line| handle_stdout(line) },
               )
               @end_time_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) * 1000).to_i #: Integer?

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

@@ -100,6 +100,21 @@ module Roast
           lines.join("\n")
         end
 
+        # Get the statistics as a hash, with aggregate and per-model usage as nested hashes
+        #
+        # #### See Also
+        # - `Agent::Usage#to_h`
+        #
+        #: () -> Hash[Symbol, untyped]
+        def to_h
+          {
+            duration_ms:,
+            num_turns:,
+            usage: usage.to_h,
+            model_usage: model_usage.transform_values(&:to_h),
+          }
+        end
+
         private
 
         #: (Numeric?, Numeric?) -> Numeric?

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

@@ -68,6 +68,13 @@ module Roast
           result
         end
 
+        # Get the token counts and cost as a hash
+        #
+        #: () -> Hash[Symbol, untyped]
+        def to_h
+          { input_tokens:, output_tokens:, cost_usd: }
+        end
+
         private
 
         #: (Numeric?, Numeric?) -> Numeric?

data/lib/roast/cogs/agent.rb

@@ -45,17 +45,70 @@ module Roast
       # The agent may make multiple turns (back-and-forth exchanges) during execution,
       # especially when using tools. Each turn is counted in the execution statistics.
       #
+      # If the cog is configured with `record_agent_runs_to`, a record of the run is appended to that file
+      # whether the run succeeds or fails.
+      #
       #: (Input) -> Output
       def execute(input)
-        output = provider.invoke(input)
-        if config.show_stats?
-          Event << { block: { header: "AGENT STATS", content: "#{output.stats}\nSession ID: #{output.session}" } }
+        started_at = Time.now
+        begin
+          output = provider.invoke(input)
+          if config.show_stats?
+            Event << { block: { header: "AGENT STATS", content: "#{output.stats}\nSession ID: #{output.session}" } }
+          end
+          output
+        rescue StandardError => e
+          error = e
+          raise
+        ensure
+          record_run(input, output, error, started_at) if config.valid_record_agent_runs_to_path
         end
-        output
       end
 
       private
 
+      #: (Input, Output?, StandardError?, Time) -> void
+      def record_run(input, output, error, started_at)
+        record = {
+          started_at: started_at.utc.iso8601(3),
+          finished_at: Time.now.utc.iso8601(3),
+          cog: { name: anonymous? ? nil : name, path: record_path },
+          provider: config.valid_provider!,
+          model: config.valid_model,
+          prompts: input.prompts,
+          system_prompt: { append: config.valid_append_system_prompt, replace: config.valid_replace_system_prompt },
+          status: run_status(output, error),
+          error: error && { class: error.class.name, message: error.message },
+          response: output&.response,
+          session: output&.session,
+          stats: output&.stats&.to_h,
+        }
+        path = config.valid_record_agent_runs_to_path.not_nil!
+        path.dirname.mkpath
+        File.write(path.to_s, "#{JSON.generate(record)}\n", mode: "a")
+      end
+
+      #: () -> Array[Hash[Symbol, untyped]]
+      def record_path
+        TaskContext.path.filter_map do |element|
+          cog = element.cog
+          execution_manager = element.execution_manager
+          if cog.present?
+            { cog: cog.type, name: cog.anonymous? ? nil : cog.name }
+          elsif execution_manager&.scope
+            { scope: execution_manager.scope, index: execution_manager.scope_index }
+          end
+        end
+      end
+
+      #: (Output?, StandardError?) -> String
+      def run_status(output, error)
+        return "timed_out" if error.is_a?(CommandRunner::TimeoutError)
+        return "failed" if error || output.nil?
+
+        "succeeded"
+      end
+
       #: () -> Provider
       def provider
         @provider ||= case config.valid_provider!