tryouts 3.3.2 → 3.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b8d7c33ad6377a7fb1c64c83e24e643c434643aa09e5451ad42bbe80c65b9c9d
-  data.tar.gz: 89cfe371c0fd575614a56702c904d0c5140db2a3a2af41d22777e459de1f4d8a
+  metadata.gz: 6b0f0a0ca7de83a58c4e822d127a963bb1fb08523d9146b24c8b33f8a2c12ff2
+  data.tar.gz: 2f4e61611e23176da42cc9bbf82a92a2cc1e9d6049943fd4d4827dcd2b34c84f
 SHA512:
-  metadata.gz: 174645930ab03bc8332e415e9dde67e6c261a66ec2aa4f5572a31841a339cb244d15da75f6d314e3e2ec2d987fb5439e03c34d35d244b37d8b81a7e5b4dbc55d
-  data.tar.gz: 524ded2d4d670ed5fce810ef363faaba2459e56979fc13e61cdd7fbad6a3cffe2cadef7e7c8f1be0901ed1d26b44185f05f8be524c0ebe60a76e3bb841be5b37
+  metadata.gz: 1505d26c47b4fb3fb75675425e6aaac3e1ba81b6f39ac8ae47622ae43acd0c19a13a16e82486663de0201f21bf7b997281744fc6d69cae6116e67065803b4a39
+  data.tar.gz: ca57f3c38348023c57f5e382fe8b45e29877393fae155a718c921550b4a2200b0fe37c1c31be4f41dcbc934527d8c6b53e74fbe88fcc574c53cbc3d765bb3534

data/README.md

@@ -1,17 +1,21 @@
-# Tryouts v3.1
+# Tryouts v3
 
 **Ruby tests that read like documentation.**
 
 A modern test framework for Ruby that uses comments to define expectations. Tryouts are meant to double as documentation, so the Ruby code should be plain and reminiscent of real code.
 
+> [!NOTE]
+> **Agent-Optimized Output**: Tryouts includes specialized output modes for LLM consumption with `--agent` flag, providing structured, token-efficient test results that are 60-80% smaller than traditional output while preserving debugging context.
+
 > [!WARNING]
-> Version 3.0+ uses Ruby's Prism parser and pattern matching, requiring Ruby 3.4+
+> Version 3.0+ uses Ruby's Prism parser and pattern matching, requiring Ruby 3.2+
 
 ## Key Features
 
 - **Documentation-style tests** using comment-based expectations (`#=>`)
 - **Great expectation syntax** for more expressive assertions (`#==>` for true, `#=/=>` for false, `#=:>` for class/module)
 - **Framework integration** write with tryouts syntax, run with RSpec or Minitest
+- **Agent-optimized output** structured, token-efficient output for LLM consumption
 - **Enhanced error reporting** with line numbers and context
 
 ## Installation
@@ -117,6 +121,13 @@ try -v    # verbose (includes source code and return values)
 try -q    # quiet mode
 try -f    # show failures only
 try -D    # debug mode
+
+# Agent-optimized output for LLMs
+try --agent                              # structured, token-efficient output
+try --agent --agent-focus summary        # show only counts and problem files
+try --agent --agent-focus first-failure  # show first failure per file
+try --agent --agent-focus critical       # show only errors/exceptions
+try --agent --agent-limit 1000          # limit output to 1000 tokens
 ```
 
 ### Exit Codes
@@ -127,14 +138,14 @@ try -D    # debug mode
 
 ## Requirements
 
-- **Ruby >= 3.2+** (for Prism parser and pattern matching)
+- **Ruby >= 3.2** (for Prism parser and pattern matching)
 - **RSpec** or **Minitest** (optional, for framework integration)
 
 ## Modern Architecture (v3+)
 
 ### Core Components
 
-- **Prism Parser**: Inhouse Ruby parsing with pattern matching for line classification
+- **Prism Parser**: Native Ruby parsing with pattern matching for line classification
 - **Data Structures**: Immutable `Data.define` classes for test representation
 - **Framework Translators**: Convert tryouts to RSpec/Minitest format
 - **CLI**: Modern command-line interface with framework selection

data/lib/tryouts/cli/formatters/agent.rb

@@ -0,0 +1,450 @@
+# lib/tryouts/cli/formatters/agent.rb
+
+require_relative 'token_budget'
+
+class Tryouts
+  class CLI
+    # Agent-optimized formatter designed for LLM context management
+    # Features:
+    # - Token budget awareness
+    # - Structured YAML-like output
+    # - No redundant file paths
+    # - Smart truncation
+    # - Hierarchical organization
+    class AgentFormatter
+      include FormatterInterface
+
+      def initialize(options = {})
+        super
+        @budget = TokenBudget.new(options[:agent_limit] || TokenBudget::DEFAULT_LIMIT)
+        @focus_mode = options[:agent_focus] || :failures
+        @collected_files = []
+        @current_file_data = nil
+        @total_stats = { files: 0, tests: 0, failures: 0, errors: 0, elapsed: 0 }
+        @output_rendered = false
+
+        # No colors in agent mode for cleaner parsing
+        @use_colors = false
+      end
+
+      # Phase-level output - collect data, don't output immediately
+      def phase_header(message, file_count: nil)
+        # Store file count for later use, but only store actual file count
+        if file_count && message.include?("FILES")
+          @total_stats[:files] = file_count
+        end
+      end
+
+      # File-level operations - start collecting file data
+      def file_start(file_path, context_info: {})
+        @current_file_data = {
+          path: relative_path(file_path),
+          tests: 0,
+          failures: [],
+          errors: [],
+          passed: 0
+        }
+      end
+
+      def file_end(file_path, context_info: {})
+        # Finalize current file data
+        if @current_file_data
+          @collected_files << @current_file_data
+          @current_file_data = nil
+        end
+        # REMOVED: No longer attempts to render here to avoid premature output
+      end
+
+      def file_parsed(_file_path, test_count:, setup_present: false, teardown_present: false)
+        @current_file_data[:tests] = test_count if @current_file_data
+        @total_stats[:tests] += test_count
+      end
+
+      def file_result(_file_path, total_tests:, failed_count:, error_count:, elapsed_time: nil)
+        # Always update global totals
+        @total_stats[:failures] += failed_count
+        @total_stats[:errors] += error_count
+        @total_stats[:elapsed] += elapsed_time if elapsed_time
+
+        # Update per-file data when available
+        if @current_file_data
+          @current_file_data[:passed] = total_tests - failed_count - error_count
+        end
+      end
+
+
+      # Test-level operations - collect failure data
+      def test_result(result_packet)
+        return unless @current_file_data
+
+        # For summary mode, we still need to collect failures for counting, just don't build detailed data
+        if result_packet.failed? || result_packet.error?
+          if @focus_mode == :summary
+            # Just track counts for summary
+            if result_packet.error?
+              @current_file_data[:errors] << { basic: true }
+            else
+              @current_file_data[:failures] << { basic: true }
+            end
+          else
+            # Build detailed failure data for other modes
+            failure_data = build_failure_data(result_packet)
+
+            if result_packet.error?
+              @current_file_data[:errors] << failure_data
+            else
+              @current_file_data[:failures] << failure_data
+            end
+
+            # Mark truncation for first-failure mode (handle limiting in render phase)
+            if (@focus_mode == :first_failure || @focus_mode == :'first-failure') &&
+               (@current_file_data[:failures].size + @current_file_data[:errors].size) > 1
+              @current_file_data[:truncated] = true
+            end
+          end
+        end
+      end
+
+      # Summary operations - reliable trigger for rendering
+      def batch_summary(failure_collector)
+        # This becomes the single, reliable trigger for rendering
+        grand_total(
+          total_tests: @total_stats[:tests],
+          failed_count: @collected_files.sum { |f| f[:failures].size },
+          error_count: @collected_files.sum { |f| f[:errors].size },
+          successful_files: @collected_files.size - @collected_files.count { |f| f[:failures].any? || f[:errors].any? },
+          total_files: @collected_files.size,
+          elapsed_time: @total_stats[:elapsed]
+        ) unless @output_rendered
+      end
+
+      def grand_total(total_tests:, failed_count:, error_count:, successful_files:, total_files:, elapsed_time:)
+        return if @output_rendered  # Prevent double rendering
+
+        @total_stats.merge!(
+          tests: total_tests,
+          failures: failed_count,
+          errors: error_count,
+          successful_files: successful_files,
+          total_files: total_files,
+          elapsed: elapsed_time
+        )
+
+        # Now render all collected data
+        render_agent_output
+        @output_rendered = true
+      end
+
+      # Override live status - not needed for agent mode
+      def live_status_capabilities
+        {
+          supports_coordination: false,
+          output_frequency: :none,
+          requires_tty: false
+        }
+      end
+
+      private
+
+      def build_failure_data(result_packet)
+        test_case = result_packet.test_case
+
+        failure_data = {
+          line: (test_case.first_expectation_line || test_case.line_range&.first || 0) + 1,
+          test: test_case.description.to_s.empty? ? 'unnamed test' : test_case.description.to_s
+        }
+
+        case result_packet.status
+        when :error
+          error = result_packet.error
+          failure_data[:error] = error ? "#{error.class.name}: #{error.message}" : 'unknown error'
+        when :failed
+          if result_packet.expected_results.any? && result_packet.actual_results.any?
+            expected = @budget.smart_truncate(result_packet.first_expected, max_tokens: 25)
+            actual = @budget.smart_truncate(result_packet.first_actual, max_tokens: 25)
+            failure_data[:expected] = expected
+            failure_data[:got] = actual
+
+            # Add diff for strings if budget allows
+            if result_packet.first_expected.is_a?(String) &&
+               result_packet.first_actual.is_a?(String) &&
+               @budget.has_budget?
+              failure_data[:diff] = generate_simple_diff(result_packet.first_expected, result_packet.first_actual)
+            end
+          else
+            failure_data[:reason] = 'test failed'
+          end
+        end
+
+        failure_data
+      end
+
+      def generate_simple_diff(expected, actual)
+        return nil unless @budget.remaining > 100  # Only if we have decent budget left
+
+        # Simple line-by-line diff
+        exp_lines = expected.split("\n")
+        act_lines = actual.split("\n")
+
+        diff_lines = []
+        diff_lines << "- #{act_lines.first}" if act_lines.any?
+        diff_lines << "+ #{exp_lines.first}" if exp_lines.any?
+
+        diff_result = diff_lines.join("\n")
+        return @budget.fit_text(diff_result) if @budget.would_exceed?(diff_result)
+        diff_result
+      end
+
+      def render_agent_output
+        case @focus_mode
+        when :summary
+          render_summary_only
+        when :critical
+          render_critical_only
+        else
+          render_full_structured
+        end
+      end
+
+      def render_summary_only
+        output = []
+
+        # Count failures manually from collected file data (same as other render methods)
+        failed_count = @collected_files.sum { |f| f[:failures].size }
+        error_count = @collected_files.sum { |f| f[:errors].size }
+        issues_count = failed_count + error_count
+        passed_count = [@total_stats[:tests] - issues_count, 0].max
+
+        if issues_count > 0
+          status = "FAIL: #{issues_count}/#{@total_stats[:tests]} tests"
+          details = []
+          details << "#{failed_count} failed" if failed_count > 0
+          details << "#{error_count} errors" if error_count > 0
+          status += " (#{details.join(', ')}, #{passed_count} passed)"
+        else
+          status = "PASS: #{@total_stats[:tests]} tests passed"
+        end
+
+        status += " (#{format_time(@total_stats[:elapsed])})" if @total_stats[:elapsed]
+
+        output << status
+
+        # Show which files had failures
+        files_with_issues = @collected_files.select { |f| f[:failures].any? || f[:errors].any? }
+        if files_with_issues.any?
+          output << ""
+          output << "Files with issues:"
+          files_with_issues.each do |file_data|
+            issue_count = file_data[:failures].size + file_data[:errors].size
+            output << "  #{file_data[:path]}: #{issue_count} issue#{'s' if issue_count != 1}"
+          end
+        end
+
+        puts output.join("\n")
+      end
+
+      def render_critical_only
+        # Only show errors (exceptions), skip assertion failures
+        critical_files = @collected_files.select { |f| f[:errors].any? }
+
+        if critical_files.empty?
+          puts "No critical errors found"
+          return
+        end
+
+        output = []
+        output << "CRITICAL: #{critical_files.size} file#{'s' if critical_files.size != 1} with errors"
+        output << ""
+
+        critical_files.each do |file_data|
+          unless @budget.has_budget?
+            output << "... (truncated due to token limit)"
+            break
+          end
+
+          output << "#{file_data[:path]}:"
+
+          file_data[:errors].each do |error|
+            error_line = "  L#{error[:line]}: #{error[:error]}"
+            if @budget.would_exceed?(error_line)
+              output << @budget.fit_text(error_line)
+            else
+              output << error_line
+              @budget.consume(error_line)
+            end
+          end
+
+          output << ""
+        end
+
+        puts output.join("\n")
+      end
+
+      def render_full_structured
+        output = []
+
+        # Header with overall stats
+        issues_count = @total_stats[:failures] + @total_stats[:errors]
+        passed_count = [@total_stats[:tests] - issues_count, 0].max
+
+        files_count = if @total_stats[:files].to_i > 0
+          @total_stats[:files]
+        else
+          @total_stats[:total_files] || @collected_files.size
+        end
+
+        if issues_count > 0
+          status_line = "FAIL: #{issues_count}/#{@total_stats[:tests]} tests (#{files_count} files, #{format_time(@total_stats[:elapsed])})"
+        else
+          status_line = "PASS: #{@total_stats[:tests]} tests (#{files_count} files, #{format_time(@total_stats[:elapsed])})"
+        end
+
+        # Always include status line
+        output << status_line
+        @budget.force_consume(status_line)
+
+        # Only show files with issues (unless focus is different)
+        files_to_show = case @focus_mode
+        when :failures, :first_failure
+          @collected_files.select { |f| f[:failures].any? || f[:errors].any? }
+        else
+          @collected_files.select { |f| f[:failures].any? || f[:errors].any? }
+        end
+
+        if files_to_show.any?
+          output << ""
+          @budget.consume("\n")
+
+          files_to_show.each do |file_data|
+            break unless @budget.has_budget?
+
+            file_section = render_file_section(file_data)
+            if @budget.would_exceed?(file_section)
+              # Try to fit what we can
+              truncated = @budget.fit_text(file_section, preserve_suffix: "\n  ... (truncated)")
+              output << truncated if truncated.length > 20  # Only if meaningful content remains
+              break
+            else
+              output << file_section
+              @budget.consume(file_section)
+            end
+          end
+        end
+
+        # Final summary line
+        summary = "Summary: #{passed_count} passed, #{@total_stats[:failures]} failed"
+        summary += ", #{@total_stats[:errors]} errors" if @total_stats[:errors] > 0
+        summary += " in #{@total_stats[:files]} files"
+
+        output << ""
+        output << summary
+
+        puts output.join("\n")
+      end
+
+      def render_file_section(file_data)
+        lines = []
+
+        # File header
+        lines << "#{file_data[:path]}:"
+
+        # For first-failure mode, only show first error or failure
+        if @focus_mode == :first_failure || @focus_mode == :'first-failure'
+          shown_count = 0
+
+          # Show first error
+          if file_data[:errors].any? && shown_count == 0
+            error = file_data[:errors].first
+            lines << "  L#{error[:line]}: #{error[:error]}"
+            lines << "    Test: #{error[:test]}" if error[:test] != 'unnamed test'
+            shown_count += 1
+          end
+
+          # Show first failure if no error was shown
+          if file_data[:failures].any? && shown_count == 0
+            failure = file_data[:failures].first
+            line_parts = ["  L#{failure[:line]}:"]
+
+            if failure[:expected] && failure[:got]
+              line_parts << "expected #{failure[:expected]}, got #{failure[:got]}"
+            elsif failure[:reason]
+              line_parts << failure[:reason]
+            end
+
+            lines << line_parts.join(' ')
+            lines << "    Test: #{failure[:test]}" if failure[:test] != 'unnamed test'
+
+            # Add diff if available and budget allows
+            if failure[:diff] && @budget.remaining > 50
+              lines << "    Diff:"
+              failure[:diff].split("\n").each { |diff_line| lines << "      #{diff_line}" }
+            end
+          end
+
+          # Show truncation notice
+          total_issues = file_data[:errors].size + file_data[:failures].size
+          if total_issues > 1
+            lines << "  ... (#{total_issues - 1} more failures not shown)"
+          end
+        else
+          # Normal mode - show all errors and failures
+          # Errors first (more critical)
+          file_data[:errors].each do |error|
+            next if error[:basic]  # Skip basic entries from summary mode
+            lines << "  L#{error[:line]}: #{error[:error]}"
+            lines << "    Test: #{error[:test]}" if error[:test] != 'unnamed test'
+          end
+
+          # Then failures
+          file_data[:failures].each do |failure|
+            next if failure[:basic]  # Skip basic entries from summary mode
+            line_parts = ["  L#{failure[:line]}:"]
+
+            if failure[:expected] && failure[:got]
+              line_parts << "expected #{failure[:expected]}, got #{failure[:got]}"
+            elsif failure[:reason]
+              line_parts << failure[:reason]
+            end
+
+            lines << line_parts.join(' ')
+            lines << "    Test: #{failure[:test]}" if failure[:test] != 'unnamed test'
+
+            # Add diff if available and budget allows
+            if failure[:diff] && @budget.remaining > 50
+              lines << "    Diff:"
+              failure[:diff].split("\n").each { |diff_line| lines << "      #{diff_line}" }
+            end
+          end
+
+          # Show truncation notice if applicable
+          if file_data[:truncated]
+            lines << "  ... (more failures not shown)"
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      def relative_path(file_path)
+        # Remove leading path components to save tokens
+        path = Pathname.new(file_path).relative_path_from(Pathname.pwd).to_s
+        # If relative path is longer, use just filename
+        path.include?('../') ? File.basename(file_path) : path
+      rescue
+        File.basename(file_path)
+      end
+
+      def format_time(seconds)
+        return '0ms' unless seconds
+
+        if seconds < 0.001
+          "#{(seconds * 1_000_000).round}μs"
+        elsif seconds < 1
+          "#{(seconds * 1000).round}ms"
+        else
+          "#{seconds.round(2)}s"
+        end
+      end
+    end
+  end
+end

data/lib/tryouts/cli/formatters/factory.rb

@@ -12,6 +12,11 @@ class Tryouts
       end
 
       def self.create_formatter(options = {})
+        # Check for agent mode first (takes precedence)
+        if options[:agent]
+          return AgentFormatter.new(options)
+        end
+
         # Map boolean flags to format symbols if format not explicitly set
         format = options[:format]&.to_sym || determine_format_from_flags(options)
 

data/lib/tryouts/cli/formatters/token_budget.rb

@@ -0,0 +1,157 @@
+# lib/tryouts/cli/formatters/token_budget.rb
+
+class Tryouts
+  class CLI
+    # Token budget tracking for agent-optimized output
+    class TokenBudget
+      DEFAULT_LIMIT = 5000
+      BUFFER_PERCENT = 0.05  # 5% buffer to avoid going over
+
+      attr_reader :limit, :used, :remaining
+
+      def initialize(limit = DEFAULT_LIMIT)
+        @limit = limit
+        @used = 0
+        @buffer_size = (@limit * BUFFER_PERCENT).to_i
+      end
+
+      # Estimate tokens in text (rough approximation: 1 token ≈ 4 characters)
+      def estimate_tokens(text)
+        return 0 if text.nil? || text.empty?
+
+        (text.length / 4.0).ceil
+      end
+
+      # Check if text would exceed budget
+      def would_exceed?(text)
+        token_count = estimate_tokens(text)
+        (@used + token_count) > (@limit - @buffer_size)
+      end
+
+      # Add text to budget if within limits
+      def consume(text)
+        return false if would_exceed?(text)
+
+        @used += estimate_tokens(text)
+        true
+      end
+
+      # Force consume (for critical information that must be included)
+      def force_consume(text)
+        @used += estimate_tokens(text)
+        true
+      end
+
+      # Get remaining budget
+      def remaining
+        [@limit - @used - @buffer_size, 0].max
+      end
+
+      # Check if we have budget remaining
+      def has_budget?
+        remaining > 0
+      end
+
+      # Get utilization percentage
+      def utilization
+        (@used.to_f / @limit * 100).round(1)
+      end
+
+      # Try to fit text within remaining budget by truncating
+      def fit_text(text, preserve_suffix: nil)
+        token_count = estimate_tokens(text)
+
+        return text if token_count <= remaining
+        return '' unless has_budget?
+
+        # Calculate how many characters we can fit
+        max_chars = remaining * 4
+
+        if preserve_suffix
+          suffix_chars = preserve_suffix.length
+          return preserve_suffix if max_chars <= suffix_chars
+
+          available_chars = max_chars - suffix_chars - 3  # 3 for "..."
+          return "#{text[0, available_chars]}...#{preserve_suffix}"
+        else
+          return text[0, max_chars - 3] + '...' if max_chars > 3
+          return ''
+        end
+      end
+
+      # Smart truncate for different data types
+      def smart_truncate(value, max_tokens: nil)
+        max_tokens ||= [remaining / 2, 50].min  # Use half remaining or 50, whichever is smaller
+        max_chars = [max_tokens.to_i * 4, 0].max
+
+        case value
+        when String
+          return value if value.length <= max_chars
+          return '...' if max_chars <= 3
+          "#{value[0, max_chars - 3]}..."
+        when Array
+          if estimate_tokens(value.inspect) <= max_tokens
+            value.inspect
+          else
+            # Show first few elements
+            truncated = []
+            char_count = 2  # for "[]"
+
+            value.each do |item|
+              item_str = item.inspect
+              if char_count + item_str.length + 2 <= max_chars - 10  # 10 chars for ", ..."
+                truncated << item
+                char_count += item_str.length + 2  # +2 for ", "
+              else
+                break
+              end
+            end
+
+            "[#{truncated.map(&:inspect).join(', ')}, ...#{value.size - truncated.size} more]"
+          end
+        when Hash
+          if estimate_tokens(value.inspect) <= max_tokens
+            value.inspect
+          else
+            # Show first few key-value pairs
+            truncated = {}
+            char_count = 2  # for "{}"
+
+            value.each do |key, val|
+              pair_str = "#{key.inspect}=>#{val.inspect}"
+              if char_count + pair_str.length + 2 <= max_chars - 10
+                truncated[key] = val
+                char_count += pair_str.length + 2
+              else
+                break
+              end
+            end
+
+            "{#{truncated.map { |k, v| "#{k.inspect}=>#{v.inspect}" }.join(', ')}, ...#{value.size - truncated.size} more}"
+          end
+        else
+          smart_truncate(value.to_s, max_tokens: max_tokens)
+        end
+      end
+
+      # Distribution strategy for budget allocation
+      def allocate_budget
+        {
+          summary: (@limit * 0.20).to_i,      # 20% for file summaries
+          failures: (@limit * 0.60).to_i,     # 60% for failure details
+          context: (@limit * 0.15).to_i,      # 15% for additional context
+          buffer: (@limit * 0.05).to_i        # 5% buffer
+        }
+      end
+
+      # Reset budget
+      def reset
+        @used = 0
+      end
+
+      def to_s
+        "TokenBudget[#{@used}/#{@limit} tokens (#{utilization}%)]"
+      end
+    end
+  end
+end

data/lib/tryouts/cli/formatters.rb

@@ -6,4 +6,6 @@ require_relative 'formatters/quiet'
 require_relative 'formatters/verbose'
 require_relative 'formatters/test_run_state'
 require_relative 'formatters/tty_status_display'
+require_relative 'formatters/token_budget'
+require_relative 'formatters/agent'
 require_relative 'formatters/factory'

data/lib/tryouts/cli/opts.rb

@@ -15,19 +15,72 @@ class Tryouts
         try --direct --shared-context test_try.rb # Explicit shared context
         try --generate-rspec test_try.rb         # Output RSpec code only
         try --inspect test_try.rb                # Inspect file structure and validation
-
-      File Format:
-        ## Test description       # Test case marker
-        code_to_test              # Ruby code
-        #=> expected_result       # Expectation (various types available)
+        try --agent test_try.rb                  # Agent-optimized structured output
+        try --agent --agent-limit 10000 tests/  # Agent mode with 10K token limit
+
+      Agent Output Modes:
+        --agent                                  # Structured, token-efficient output
+        --agent-focus summary                    # Show counts and problem files only
+        --agent-focus first-failure              # Show first failure per file
+        --agent-focus critical                   # Show errors/exceptions only
+        --agent-limit 1000                      # Limit output to 1000 tokens
+
+      File Naming & Organization:
+        Files must end with '_try.rb' or '.try.rb' (e.g., auth_service_try.rb, user_model.try.rb)
+        Auto-discovery searches: ./try/, ./tryouts/, ./*_try.rb, ./*.try.rb patterns
+        Organize by feature/module: try/models/, try/services/, try/api/
+
+      Testcase Structure (3 required parts)
+        ## This is the description
+        echo 'This is ruby code under test'
+        true
+        #=> true  # this is the expected result
+
+      File Structure (3 sections):
+        # Setup section (optional) - runs once before all tests
+        @shared_var = "available to all test cases"
+
+        ## TEST: Feature description
+        # Test case body with plain Ruby code
+        result = some_operation()
+        #=> expected_value
+
+        # Teardown section (optional) - runs once after all tests
+
+      Context Guidelines:
+        Shared Context (default): Instance variables persist across test cases
+          - Use for: Integration testing, stateful scenarios, realistic workflows
+          - Caution: Test order matters, state accumulates
+
+        Fresh Context (--rspec/--minitest): Each test gets isolated environment
+          - Use for: Unit testing, independent test cases
+          - Setup variables copied to each test, but changes don't persist
+
+      Writing Quality Tryouts:
+        - Use realistic, plain Ruby code (avoid mocks, test harnesses)
+        - Test descriptions start with ##, be specific about what's being tested
+        - One result per test case (last expression is the result)
+        - Use appropriate expectation types for clarity (#==> for boolean, #=:> for types)
+        - Keep tests focused and readable - they serve as documentation
 
       Great Expectations System:
-        Multiple expectation types are supported for different testing needs.
-
         #=>   Value equality        #==> Must be true         #=/=> Must be false
         #=|>  True OR false         #=!>  Must raise error    #=:>  Type matching
         #=~>  Regex matching        #=%>  Time constraints    #=*>  Non-nil result
         #=1>  STDOUT content        #=2>  STDERR content      #=<>  Intentional failure
+
+      Exception Testing:
+        # Method 1: Rescue and test exception
+        begin
+          risky_operation
+        rescue StandardError => e
+          e.class
+        end
+        #=> StandardError
+
+        # Method 2: Let it raise and test with #=!>
+        risky_operation
+        #=!> error.is_a?(StandardError)
     HELP
 
     class << self
@@ -70,6 +123,20 @@ class Tryouts
             options[:parallel_threads] = threads.to_i if threads && threads.to_i > 0
           end
 
+          opts.separator "\nAgent-Optimized Output:"
+          opts.on('-a', '--agent', 'Agent-optimized structured output for LLM context management') do
+            options[:agent] = true
+          end
+          opts.on('--agent-limit TOKENS', Integer, 'Limit total output to token budget (default: 5000)') do |limit|
+            options[:agent] = true
+            options[:agent_limit] = limit
+          end
+          opts.on('--agent-focus TYPE', %w[failures first-failure summary critical],
+                  'Focus mode: failures, first-failure, summary, critical (default: failures)') do |focus|
+            options[:agent] = true
+            options[:agent_focus] = focus.to_sym
+          end
+
           opts.separator "\nParser Options:"
           opts.on('--enhanced-parser', 'Use enhanced parser with inhouse comment extraction (default)') { options[:parser] = :enhanced }
           opts.on('--legacy-parser', 'Use legacy prism parser') { options[:parser] = :prism }

data/lib/tryouts/test_runner.rb

@@ -38,7 +38,13 @@ class Tryouts
       result = process_files
       show_failure_summary
       show_grand_total if @global_tally[:aggregator].get_file_counts[:total] > 1
-      result
+
+      # For agent critical mode, only count errors as failures
+      if @options[:agent] && (@options[:agent_focus] == :critical || @options[:agent_focus] == 'critical')
+        @global_tally[:aggregator].get_display_counts[:errors]
+      else
+        result
+      end
     end
 
     private
@@ -107,7 +113,7 @@ class Tryouts
       executor = Concurrent::ThreadPoolExecutor.new(
         min_threads: 1,
         max_threads: pool_size,
-        max_queue: pool_size * 2, # Reasonable queue size
+        max_queue: @files.length, # Queue size must accommodate all files
         fallback_policy: :abort # Raise exception if pool and queue are exhausted
       )
 

data/lib/tryouts/version.rb

@@ -1,5 +1,5 @@
 # lib/tryouts/version.rb
 
 class Tryouts
-  VERSION = '3.3.2'
+  VERSION = '3.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tryouts
 version: !ruby/object:Gem::Version
-  version: 3.3.2
+  version: 3.4.0
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -137,6 +137,7 @@ files:
 - lib/tryouts.rb
 - lib/tryouts/cli.rb
 - lib/tryouts/cli/formatters.rb
+- lib/tryouts/cli/formatters/agent.rb
 - lib/tryouts/cli/formatters/base.rb
 - lib/tryouts/cli/formatters/compact.rb
 - lib/tryouts/cli/formatters/factory.rb
@@ -144,6 +145,7 @@ files:
 - lib/tryouts/cli/formatters/output_manager.rb
 - lib/tryouts/cli/formatters/quiet.rb
 - lib/tryouts/cli/formatters/test_run_state.rb
+- lib/tryouts/cli/formatters/token_budget.rb
 - lib/tryouts/cli/formatters/tty_status_display.rb
 - lib/tryouts/cli/formatters/verbose.rb
 - lib/tryouts/cli/modes/generate.rb