aidp 0.34.0 → 0.39.3

data/lib/aidp/harness/usage_limit.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Aidp
+  module Harness
+    # Immutable value object representing usage limit configuration
+    # Encapsulates limit settings for a provider with tier-based limits
+    class UsageLimit
+      VALID_PERIODS = %w[daily weekly monthly].freeze
+      VALID_TIERS = %w[mini standard thinking advanced pro max].freeze
+      DEFAULT_PERIOD = "monthly"
+      DEFAULT_RESET_DAY = 1
+
+      attr_reader :enabled, :period, :reset_day, :tier_limits, :max_tokens, :max_cost
+
+      # Create a new UsageLimit from configuration hash
+      #
+      # @param config [Hash] Configuration hash with usage limit settings
+      # @return [UsageLimit] Immutable usage limit instance
+      def self.from_config(config)
+        return new(enabled: false) unless config.is_a?(Hash)
+
+        new(
+          enabled: config[:enabled] == true,
+          period: normalize_period(config[:period]),
+          reset_day: config[:reset_day] || DEFAULT_RESET_DAY,
+          tier_limits: parse_tier_limits(config[:tier_limits]),
+          max_tokens: config[:max_tokens],
+          max_cost: config[:max_cost]
+        )
+      end
+
+      def initialize(enabled: true, period: DEFAULT_PERIOD, reset_day: DEFAULT_RESET_DAY,
+        tier_limits: {}, max_tokens: nil, max_cost: nil)
+        @enabled = enabled
+        @period = validate_period(period)
+        @reset_day = validate_reset_day(reset_day)
+        @tier_limits = freeze_tier_limits(tier_limits)
+        @max_tokens = max_tokens&.to_i
+        @max_cost = max_cost&.to_f
+        freeze
+      end
+
+      # Check if limits are enabled and configured
+      def enabled?
+        @enabled
+      end
+
+      # Get limits for a specific tier
+      #
+      # @param tier [String, Symbol] The tier name (mini, standard, advanced, etc.)
+      # @return [Hash] Tier-specific limits or global limits
+      def limits_for_tier(tier)
+        tier_key = tier.to_s.downcase
+
+        # Map thinking tier names to usage limit tiers
+        tier_key = case tier_key
+        when "thinking", "pro", "max" then "advanced"
+        when "standard" then "standard"
+        else tier_key
+        end
+
+        tier_config = @tier_limits[tier_key] || @tier_limits[tier_key.to_sym]
+
+        if tier_config
+          {
+            max_tokens: tier_config[:max_tokens],
+            max_cost: tier_config[:max_cost]
+          }
+        else
+          # Fall back to global limits
+          {
+            max_tokens: @max_tokens,
+            max_cost: @max_cost
+          }
+        end
+      end
+
+      # Check if usage would exceed limits
+      #
+      # @param current_tokens [Integer] Current token count
+      # @param current_cost [Float] Current cost
+      # @param tier [String] The tier to check against
+      # @return [Hash] Result with :exceeded boolean and :reason
+      def exceeds_limit?(current_tokens:, current_cost:, tier: "standard")
+        return {exceeded: false, reason: nil} unless enabled?
+
+        limits = limits_for_tier(tier)
+
+        if limits[:max_tokens] && current_tokens >= limits[:max_tokens]
+          return {
+            exceeded: true,
+            reason: "Token limit exceeded: #{current_tokens}/#{limits[:max_tokens]}"
+          }
+        end
+
+        if limits[:max_cost] && current_cost >= limits[:max_cost]
+          return {
+            exceeded: true,
+            reason: "Cost limit exceeded: $#{format("%.2f", current_cost)}/$#{format("%.2f", limits[:max_cost])}"
+          }
+        end
+
+        {exceeded: false, reason: nil}
+      end
+
+      # Value equality
+      def ==(other)
+        return false unless other.is_a?(UsageLimit)
+
+        enabled == other.enabled &&
+          period == other.period &&
+          reset_day == other.reset_day &&
+          tier_limits == other.tier_limits &&
+          max_tokens == other.max_tokens &&
+          max_cost == other.max_cost
+      end
+
+      alias_method :eql?, :==
+
+      def hash
+        [enabled, period, reset_day, tier_limits, max_tokens, max_cost].hash
+      end
+
+      # Convert to configuration hash
+      def to_h
+        {
+          enabled: @enabled,
+          period: @period,
+          reset_day: @reset_day,
+          tier_limits: @tier_limits.transform_values(&:to_h),
+          max_tokens: @max_tokens,
+          max_cost: @max_cost
+        }.compact
+      end
+
+      def self.normalize_period(period)
+        return DEFAULT_PERIOD unless period
+
+        period_str = period.to_s.downcase
+        VALID_PERIODS.include?(period_str) ? period_str : DEFAULT_PERIOD
+      end
+
+      def self.parse_tier_limits(tier_limits)
+        return {} unless tier_limits.is_a?(Hash)
+
+        tier_limits.transform_values do |limits|
+          next {} unless limits.is_a?(Hash)
+
+          {
+            max_tokens: limits[:max_tokens] || limits["max_tokens"],
+            max_cost: limits[:max_cost] || limits["max_cost"]
+          }.compact
+        end
+      end
+
+      private_class_method :normalize_period, :parse_tier_limits
+
+      private
+
+      def validate_period(period)
+        period_str = period.to_s.downcase
+        VALID_PERIODS.include?(period_str) ? period_str : DEFAULT_PERIOD
+      end
+
+      def validate_reset_day(day)
+        day_int = day.to_i
+        day_int.between?(1, 28) ? day_int : DEFAULT_RESET_DAY
+      end
+
+      def freeze_tier_limits(limits)
+        return {}.freeze unless limits.is_a?(Hash)
+
+        limits.transform_values do |tier_config|
+          tier_config.is_a?(Hash) ? tier_config.freeze : {}
+        end.freeze
+      end
+    end
+  end
+end

data/lib/aidp/harness/usage_limit_enforcer.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require_relative "usage_limit"
+require_relative "usage_limit_tracker"
+
+module Aidp
+  module Harness
+    # Exception raised when usage limits are exceeded
+    # Contains context about the exceeded limit for fallback handling
+    class UsageLimitExceededError < StandardError
+      attr_reader :provider_name, :tier, :current_tokens, :current_cost,
+        :max_tokens, :max_cost, :period_description
+
+      def initialize(provider_name:, tier:, current_tokens:, current_cost:,
+        max_tokens:, max_cost:, period_description:, message: nil)
+        @provider_name = provider_name
+        @tier = tier
+        @current_tokens = current_tokens
+        @current_cost = current_cost
+        @max_tokens = max_tokens
+        @max_cost = max_cost
+        @period_description = period_description
+
+        super(message || default_message)
+      end
+
+      def to_h
+        {
+          type: "usage_limit_exceeded",
+          provider: @provider_name,
+          tier: @tier,
+          current_tokens: @current_tokens,
+          current_cost: @current_cost,
+          max_tokens: @max_tokens,
+          max_cost: @max_cost,
+          period: @period_description,
+          timestamp: Time.now.iso8601
+        }
+      end
+
+      private
+
+      def default_message
+        parts = []
+        parts << "Usage limit exceeded for #{@provider_name} (tier: #{@tier})"
+        parts << "Period: #{@period_description}"
+
+        if @max_tokens && @current_tokens >= @max_tokens
+          parts << "Tokens: #{@current_tokens}/#{@max_tokens}"
+        end
+
+        if @max_cost && @current_cost >= @max_cost
+          parts << "Cost: $#{format("%.2f", @current_cost)}/$#{format("%.2f", @max_cost)}"
+        end
+
+        parts.join(". ")
+      end
+    end
+
+    # Application service for enforcing usage limits
+    # Coordinates between UsageLimit config and UsageLimitTracker
+    class UsageLimitEnforcer
+      attr_reader :provider_name, :usage_limit, :tracker
+
+      # Initialize the enforcer with configuration
+      #
+      # @param provider_name [String] Name of the provider
+      # @param usage_limit [UsageLimit] Usage limit configuration
+      # @param tracker [UsageLimitTracker] Tracker instance for usage data
+      def initialize(provider_name:, usage_limit:, tracker:)
+        @provider_name = provider_name.to_s
+        @usage_limit = usage_limit
+        @tracker = tracker
+
+        Aidp.log_debug("usage_limit_enforcer", "initialized",
+          provider: @provider_name,
+          enabled: @usage_limit.enabled?,
+          period: @usage_limit.period)
+      end
+
+      # Check if usage limits allow a request before making API call
+      #
+      # @param tier [String] The tier for this request
+      # @raise [UsageLimitExceededError] If limits are exceeded
+      def check_before_request(tier: "standard")
+        Aidp.log_debug("usage_limit_enforcer", "checking_limits",
+          provider: @provider_name,
+          tier: tier)
+
+        return unless @usage_limit.enabled?
+
+        current = @tracker.current_usage(
+          period_type: @usage_limit.period,
+          reset_day: @usage_limit.reset_day
+        )
+
+        limits = @usage_limit.limits_for_tier(tier)
+        check_result = @usage_limit.exceeds_limit?(
+          current_tokens: current[:total_tokens],
+          current_cost: current[:total_cost],
+          tier: tier
+        )
+
+        if check_result[:exceeded]
+          Aidp.log_warn("usage_limit_enforcer", "limit_exceeded",
+            provider: @provider_name,
+            tier: tier,
+            reason: check_result[:reason])
+
+          raise UsageLimitExceededError.new(
+            provider_name: @provider_name,
+            tier: tier,
+            current_tokens: current[:total_tokens],
+            current_cost: current[:total_cost],
+            max_tokens: limits[:max_tokens],
+            max_cost: limits[:max_cost],
+            period_description: current[:period_description]
+          )
+        end
+
+        Aidp.log_debug("usage_limit_enforcer", "limits_ok",
+          provider: @provider_name,
+          tier: tier,
+          tokens: current[:total_tokens],
+          cost: current[:total_cost])
+      end
+
+      # Record usage after a successful API request
+      #
+      # @param tokens [Integer] Tokens used in the request
+      # @param cost [Float] Cost of the request
+      # @param tier [String] Tier used for the request
+      def record_after_request(tokens:, cost:, tier: "standard")
+        return unless @usage_limit.enabled?
+
+        @tracker.record_usage(
+          tokens: tokens,
+          cost: cost,
+          tier: tier,
+          period_type: @usage_limit.period,
+          reset_day: @usage_limit.reset_day
+        )
+      end
+
+      # Check if limits would be exceeded by additional usage
+      # Non-raising version for checking without blocking
+      #
+      # @param additional_tokens [Integer] Additional tokens to add
+      # @param additional_cost [Float] Additional cost to add
+      # @param tier [String] The tier to check
+      # @return [Hash] Result with :would_exceed and :headroom
+      def check_headroom(additional_tokens: 0, additional_cost: 0.0, tier: "standard")
+        return {would_exceed: false, headroom: {tokens: nil, cost: nil}} unless @usage_limit.enabled?
+
+        current = @tracker.current_usage(
+          period_type: @usage_limit.period,
+          reset_day: @usage_limit.reset_day
+        )
+
+        limits = @usage_limit.limits_for_tier(tier)
+
+        projected_tokens = current[:total_tokens] + additional_tokens
+        projected_cost = current[:total_cost] + additional_cost
+
+        token_headroom = limits[:max_tokens] ? limits[:max_tokens] - current[:total_tokens] : nil
+        cost_headroom = limits[:max_cost] ? limits[:max_cost] - current[:total_cost] : nil
+
+        would_exceed = false
+        would_exceed = true if limits[:max_tokens] && projected_tokens >= limits[:max_tokens]
+        would_exceed = true if limits[:max_cost] && projected_cost >= limits[:max_cost]
+
+        {
+          would_exceed: would_exceed,
+          headroom: {
+            tokens: token_headroom,
+            cost: cost_headroom
+          },
+          current: {
+            tokens: current[:total_tokens],
+            cost: current[:total_cost]
+          },
+          limits: limits
+        }
+      end
+
+      # Get usage summary for display
+      #
+      # @return [Hash] Usage summary with current values, limits, and percentages
+      def usage_summary
+        return {enabled: false} unless @usage_limit.enabled?
+
+        current = @tracker.current_usage(
+          period_type: @usage_limit.period,
+          reset_day: @usage_limit.reset_day
+        )
+
+        # Aggregate across common tiers
+        tiers_summary = %w[mini standard advanced].map do |tier|
+          limits = @usage_limit.limits_for_tier(tier)
+          tier_usage = @tracker.tier_usage(
+            tier: tier,
+            period_type: @usage_limit.period,
+            reset_day: @usage_limit.reset_day
+          )
+
+          {
+            tier: tier,
+            tokens: tier_usage[:tokens],
+            cost: tier_usage[:cost],
+            requests: tier_usage[:requests],
+            max_tokens: limits[:max_tokens],
+            max_cost: limits[:max_cost],
+            token_percent: calculate_percent(tier_usage[:tokens], limits[:max_tokens]),
+            cost_percent: calculate_percent(tier_usage[:cost], limits[:max_cost])
+          }
+        end
+
+        {
+          enabled: true,
+          provider: @provider_name,
+          period: @usage_limit.period,
+          period_description: current[:period_description],
+          total_tokens: current[:total_tokens],
+          total_cost: current[:total_cost],
+          total_requests: current[:request_count],
+          remaining_seconds: current[:remaining_seconds],
+          tiers: tiers_summary
+        }
+      end
+
+      private
+
+      def calculate_percent(current, max)
+        return nil unless max&.positive?
+
+        ((current.to_f / max) * 100).round(1)
+      end
+    end
+  end
+end