aidp 0.34.1 → 0.39.3

data/lib/aidp/harness/usage_limit_tracker.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require "yaml"
+require "fileutils"
+require_relative "usage_period"
+require_relative "../rescue_logging"
+
+module Aidp
+  module Harness
+    # Domain service for tracking usage metrics per provider and period
+    # Handles recording usage, querying current usage, and period resets
+    class UsageLimitTracker
+      include Aidp::RescueLogging
+
+      # Maximum number of historical periods to retain for trend analysis
+      MAX_HISTORY_PERIODS = 12
+
+      attr_reader :provider_name, :project_dir
+
+      def initialize(provider_name:, project_dir:, metrics_repo: nil)
+        @provider_name = provider_name.to_s
+        @project_dir = project_dir
+        @metrics_repo = metrics_repo
+        @usage_file = File.join(project_dir, ".aidp", "usage_tracking", "#{@provider_name}.yml")
+        @usage_data = nil
+        @lock = Mutex.new if defined?(Mutex)
+
+        Aidp.log_debug("usage_limit_tracker", "initialized",
+          provider: @provider_name,
+          project_dir: @project_dir)
+      end
+
+      # Record usage for a request
+      #
+      # @param tokens [Integer] Number of tokens used
+      # @param cost [Float] Cost incurred
+      # @param tier [String] Tier used (mini, standard, advanced, etc.)
+      # @param period_type [String] Period type (daily, weekly, monthly)
+      # @param reset_day [Integer] Reset day for monthly periods
+      def record_usage(tokens:, cost:, tier: "standard", period_type: "monthly", reset_day: 1)
+        Aidp.log_debug("usage_limit_tracker", "recording_usage",
+          provider: @provider_name,
+          tokens: tokens,
+          cost: cost,
+          tier: tier)
+
+        return unless tokens.positive? || cost.positive?
+
+        with_lock do
+          data = load_usage_data
+          period = UsagePeriod.current(period_type: period_type, reset_day: reset_day)
+          period_key = period.period_key
+
+          # Initialize period data if needed
+          data[:periods] ||= {}
+          period_sym = period_key.to_sym
+          data[:periods][period_sym] ||= new_period_data(period)
+
+          # Update usage metrics
+          period_data = data[:periods][period_sym]
+          period_data[:total_tokens] = (period_data[:total_tokens] || 0) + tokens
+          period_data[:total_cost] = (period_data[:total_cost] || 0.0) + cost
+          period_data[:request_count] = (period_data[:request_count] || 0) + 1
+          period_data[:last_updated] = Time.now.iso8601
+
+          # Update tier-specific usage
+          tier_key = tier.to_s.downcase
+          period_data[:tier_usage] ||= {}
+          period_data[:tier_usage][tier_key] ||= {tokens: 0, cost: 0.0, requests: 0}
+          period_data[:tier_usage][tier_key][:tokens] += tokens
+          period_data[:tier_usage][tier_key][:cost] += cost
+          period_data[:tier_usage][tier_key][:requests] += 1
+
+          # Prune old periods
+          prune_old_periods(data)
+
+          # Save updated data
+          save_usage_data(data)
+          @usage_data = data
+        end
+      end
+
+      # Get current usage for a period
+      #
+      # @param period_type [String] Period type (daily, weekly, monthly)
+      # @param reset_day [Integer] Reset day for monthly periods
+      # @return [Hash] Current usage data with keys:
+      #   - :period_key [String] Period identifier (e.g., "2024-01")
+      #   - :period_description [String] Human-readable period description
+      #   - :total_tokens [Integer] Total tokens used in period
+      #   - :total_cost [Float] Total cost incurred in period
+      #   - :request_count [Integer] Number of requests made
+      #   - :tier_usage [Hash] Usage breakdown by tier
+      #   - :start_time [Time] Period start time
+      #   - :end_time [Time] Period end time
+      #   - :remaining_seconds [Integer] Seconds until period ends
+      def current_usage(period_type: "monthly", reset_day: 1)
+        period = UsagePeriod.current(period_type: period_type, reset_day: reset_day)
+        period_key = period.period_key
+
+        data = load_usage_data
+        period_data = data[:periods]&.[](period_key.to_sym)
+
+        if period_data
+          {
+            period_key: period_key,
+            period_description: period.description,
+            total_tokens: period_data[:total_tokens] || 0,
+            total_cost: period_data[:total_cost] || 0.0,
+            request_count: period_data[:request_count] || 0,
+            tier_usage: period_data[:tier_usage] || {},
+            start_time: period.start_time,
+            end_time: period.end_time,
+            remaining_seconds: period.remaining_seconds
+          }
+        else
+          {
+            period_key: period_key,
+            period_description: period.description,
+            total_tokens: 0,
+            total_cost: 0.0,
+            request_count: 0,
+            tier_usage: {},
+            start_time: period.start_time,
+            end_time: period.end_time,
+            remaining_seconds: period.remaining_seconds
+          }
+        end
+      end
+
+      # Get usage for a specific tier in the current period
+      #
+      # @param tier [String] Tier name
+      # @param period_type [String] Period type
+      # @param reset_day [Integer] Reset day
+      # @return [Hash] Tier-specific usage data
+      def tier_usage(tier:, period_type: "monthly", reset_day: 1)
+        usage = current_usage(period_type: period_type, reset_day: reset_day)
+        tier_key = tier.to_s.downcase
+
+        tier_data = usage[:tier_usage][tier_key] || usage[:tier_usage][tier_key.to_sym]
+
+        if tier_data
+          {
+            tokens: tier_data[:tokens] || tier_data["tokens"] || 0,
+            cost: tier_data[:cost] || tier_data["cost"] || 0.0,
+            requests: tier_data[:requests] || tier_data["requests"] || 0
+          }
+        else
+          {tokens: 0, cost: 0.0, requests: 0}
+        end
+      end
+
+      # Get usage history across multiple periods
+      #
+      # @param limit [Integer] Maximum number of periods to return
+      # @return [Array<Hash>] Array of period usage data, newest first
+      # @note Sorting relies on lexicographic ordering of period keys (e.g., "2024-01", "2024-W01")
+      #       which produces correct chronological order for ISO-formatted date strings
+      def usage_history(limit: MAX_HISTORY_PERIODS)
+        data = load_usage_data
+        return [] unless data[:periods].is_a?(Hash)
+
+        data[:periods]
+          .sort_by { |key, _| key }
+          .reverse
+          .take(limit)
+          .map do |key, period_data|
+            {
+              period_key: key,
+              total_tokens: period_data[:total_tokens] || 0,
+              total_cost: period_data[:total_cost] || 0.0,
+              request_count: period_data[:request_count] || 0,
+              tier_usage: period_data[:tier_usage] || {}
+            }
+          end
+      end
+
+      # Reset usage for the current period (for testing or manual reset)
+      #
+      # @param period_type [String] Period type
+      # @param reset_day [Integer] Reset day
+      def reset_current_period(period_type: "monthly", reset_day: 1)
+        Aidp.log_warn("usage_limit_tracker", "resetting_current_period",
+          provider: @provider_name,
+          period_type: period_type)
+
+        with_lock do
+          period = UsagePeriod.current(period_type: period_type, reset_day: reset_day)
+          period_key = period.period_key
+
+          data = load_usage_data
+          data[:periods]&.delete(period_key.to_sym)
+
+          save_usage_data(data)
+          @usage_data = data
+        end
+      end
+
+      # Clear all usage data (for testing or user request)
+      def clear_all_usage
+        Aidp.log_warn("usage_limit_tracker", "clearing_all_usage",
+          provider: @provider_name)
+
+        with_lock do
+          File.delete(@usage_file) if File.exist?(@usage_file)
+          @usage_data = nil
+        end
+      end
+
+      private
+
+      def load_usage_data
+        return @usage_data if @usage_data
+
+        ensure_directory
+
+        if File.exist?(@usage_file)
+          raw_data = YAML.safe_load_file(@usage_file,
+            permitted_classes: [Time, Date, Symbol],
+            aliases: true)
+          @usage_data = symbolize_keys(raw_data) if raw_data.is_a?(Hash)
+        end
+
+        @usage_data ||= {provider: @provider_name, periods: {}}
+      rescue => e
+        log_rescue(e, component: "usage_limit_tracker", action: "load_usage_data", fallback: {})
+        @usage_data = {provider: @provider_name, periods: {}}
+      end
+
+      def save_usage_data(data)
+        ensure_directory
+
+        # Write atomically using temp file + rename
+        temp_file = "#{@usage_file}.tmp"
+        File.write(temp_file, YAML.dump(stringify_keys(data)))
+        File.rename(temp_file, @usage_file)
+      rescue => e
+        log_rescue(e, component: "usage_limit_tracker", action: "save_usage_data", fallback: nil)
+        File.delete(temp_file) if File.exist?(temp_file)
+      end
+
+      def ensure_directory
+        dir = File.dirname(@usage_file)
+        FileUtils.mkdir_p(dir) unless File.directory?(dir)
+      end
+
+      def new_period_data(period)
+        {
+          period_type: period.period_type,
+          start_time: period.start_time.iso8601,
+          end_time: period.end_time.iso8601,
+          total_tokens: 0,
+          total_cost: 0.0,
+          request_count: 0,
+          tier_usage: {},
+          created_at: Time.now.iso8601,
+          last_updated: Time.now.iso8601
+        }
+      end
+
+      def prune_old_periods(data)
+        return unless data[:periods].is_a?(Hash)
+        return if data[:periods].size <= MAX_HISTORY_PERIODS
+
+        # Keep only the most recent periods
+        sorted_keys = data[:periods].keys.sort.reverse
+        keys_to_remove = sorted_keys[MAX_HISTORY_PERIODS..]
+
+        keys_to_remove&.each do |key|
+          data[:periods].delete(key)
+        end
+      end
+
+      def with_lock(&block)
+        if @lock
+          @lock.synchronize(&block)
+        else
+          yield
+        end
+      end
+
+      def symbolize_keys(hash)
+        return hash unless hash.is_a?(Hash)
+
+        hash.transform_keys(&:to_sym).transform_values do |v|
+          case v
+          when Hash then symbolize_keys(v)
+          when Array then v.map { |i| i.is_a?(Hash) ? symbolize_keys(i) : i }
+          else v
+          end
+        end
+      end
+
+      def stringify_keys(hash)
+        return hash unless hash.is_a?(Hash)
+
+        hash.transform_keys(&:to_s).transform_values do |v|
+          case v
+          when Hash then stringify_keys(v)
+          when Array then v.map { |i| i.is_a?(Hash) ? stringify_keys(i) : i }
+          else v
+          end
+        end
+      end
+    end
+  end
+end

data/lib/aidp/harness/usage_period.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "time"
+require "date"
+
+module Aidp
+  module Harness
+    # Immutable value object representing a usage tracking period
+    # Handles time period calculations, boundaries, and reset logic
+    class UsagePeriod
+      PERIOD_TYPES = %w[daily weekly monthly].freeze
+
+      attr_reader :period_type, :reset_day, :start_time, :end_time
+
+      # Create a UsagePeriod for the current time
+      #
+      # @param period_type [String] Type of period: daily, weekly, monthly
+      # @param reset_day [Integer] Day of month for reset (1-28 for monthly)
+      # @param reference_time [Time] Reference time (defaults to now)
+      # @return [UsagePeriod] Period instance
+      def self.current(period_type:, reset_day: 1, reference_time: Time.now)
+        new(
+          period_type: period_type,
+          reset_day: reset_day,
+          reference_time: reference_time
+        )
+      end
+
+      # Create a UsagePeriod from a stored period key
+      #
+      # @param period_key [String] Period key (e.g., "2024-01", "2024-W01", "2024-01-15")
+      # @param period_type [String] Type of period
+      # @return [UsagePeriod] Period instance
+      def self.from_key(period_key, period_type:)
+        reference_time = parse_period_key(period_key, period_type)
+        new(period_type: period_type, reference_time: reference_time)
+      end
+
+      def initialize(period_type:, reset_day: 1, reference_time: Time.now)
+        @period_type = validate_period_type(period_type)
+        @reset_day = validate_reset_day(reset_day)
+        @reference_time = reference_time
+
+        calculate_boundaries
+        freeze
+      end
+
+      # Generate a unique key for this period (for storage)
+      #
+      # @return [String] Period key suitable for use as hash key
+      def period_key
+        case @period_type
+        when "daily"
+          @start_time.strftime("%Y-%m-%d")
+        when "weekly"
+          @start_time.strftime("%Y-W%V")
+        when "monthly"
+          @start_time.strftime("%Y-%m")
+        end
+      end
+
+      # Check if a given time falls within this period
+      #
+      # @param time [Time] Time to check
+      # @return [Boolean] True if time is within period
+      def contains?(time)
+        time >= @start_time && time < @end_time
+      end
+
+      # Check if this period has ended
+      #
+      # @param current_time [Time] Current time (defaults to now)
+      # @return [Boolean] True if period has ended
+      def ended?(current_time = Time.now)
+        current_time >= @end_time
+      end
+
+      # Get the next period after this one
+      #
+      # @return [UsagePeriod] Next period instance
+      def next_period
+        self.class.new(
+          period_type: @period_type,
+          reset_day: @reset_day,
+          reference_time: @end_time + 1
+        )
+      end
+
+      # Get the previous period before this one
+      #
+      # @return [UsagePeriod] Previous period instance
+      def previous_period
+        self.class.new(
+          period_type: @period_type,
+          reset_day: @reset_day,
+          reference_time: @start_time - 1
+        )
+      end
+
+      # Calculate remaining time in this period
+      #
+      # @param current_time [Time] Current time (defaults to now)
+      # @return [Integer] Seconds remaining in period
+      def remaining_seconds(current_time = Time.now)
+        return 0 if ended?(current_time)
+
+        (@end_time - current_time).to_i
+      end
+
+      # Human-readable period description
+      #
+      # @return [String] Period description
+      def description
+        case @period_type
+        when "daily"
+          @start_time.strftime("%B %d, %Y")
+        when "weekly"
+          "Week of #{@start_time.strftime("%B %d, %Y")}"
+        when "monthly"
+          @start_time.strftime("%B %Y")
+        end
+      end
+
+      # Value equality
+      def ==(other)
+        return false unless other.is_a?(UsagePeriod)
+
+        period_type == other.period_type &&
+          reset_day == other.reset_day &&
+          start_time == other.start_time &&
+          end_time == other.end_time
+      end
+
+      alias_method :eql?, :==
+
+      def hash
+        [period_type, reset_day, start_time, end_time].hash
+      end
+
+      # Convert to hash for serialization
+      def to_h
+        {
+          period_type: @period_type,
+          reset_day: @reset_day,
+          start_time: @start_time.iso8601,
+          end_time: @end_time.iso8601,
+          period_key: period_key
+        }
+      end
+
+      def self.parse_period_key(period_key, period_type)
+        case period_type
+        when "daily"
+          Time.parse(period_key)
+        when "weekly"
+          # Parse ISO week format (e.g., "2024-W01")
+          year, week = period_key.split("-W")
+          Date.commercial(year.to_i, week.to_i, 1).to_time
+        when "monthly"
+          Time.parse("#{period_key}-01")
+        else
+          Time.now
+        end
+      rescue ArgumentError
+        Time.now
+      end
+
+      private_class_method :parse_period_key
+
+      private
+
+      def validate_period_type(period_type)
+        type_str = period_type.to_s.downcase
+        PERIOD_TYPES.include?(type_str) ? type_str : "monthly"
+      end
+
+      def validate_reset_day(day)
+        day_int = day.to_i
+        day_int.between?(1, 28) ? day_int : 1
+      end
+
+      def calculate_boundaries
+        case @period_type
+        when "daily"
+          calculate_daily_boundaries
+        when "weekly"
+          calculate_weekly_boundaries
+        when "monthly"
+          calculate_monthly_boundaries
+        end
+      end
+
+      def calculate_daily_boundaries
+        @start_time = Time.new(
+          @reference_time.year,
+          @reference_time.month,
+          @reference_time.day,
+          0, 0, 0
+        )
+        @end_time = @start_time + (24 * 60 * 60)
+      end
+
+      def calculate_weekly_boundaries
+        # Start on Monday (wday 1), end on Sunday
+        days_since_monday = (@reference_time.wday - 1) % 7
+        monday = @reference_time - (days_since_monday * 24 * 60 * 60)
+        @start_time = Time.new(monday.year, monday.month, monday.day, 0, 0, 0)
+        @end_time = @start_time + (7 * 24 * 60 * 60)
+      end
+
+      def calculate_monthly_boundaries
+        year = @reference_time.year
+        month = @reference_time.month
+        day = @reference_time.day
+
+        # Determine if we're before or after the reset day in current month
+        if day >= @reset_day
+          # Current period started this month
+          @start_time = Time.new(year, month, @reset_day, 0, 0, 0)
+          # End at reset day next month
+          next_month = (month == 12) ? 1 : month + 1
+          next_year = (month == 12) ? year + 1 : year
+          @end_time = Time.new(next_year, next_month, @reset_day, 0, 0, 0)
+        else
+          # Current period started last month
+          prev_month = (month == 1) ? 12 : month - 1
+          prev_year = (month == 1) ? year - 1 : year
+          @start_time = Time.new(prev_year, prev_month, @reset_day, 0, 0, 0)
+          @end_time = Time.new(year, month, @reset_day, 0, 0, 0)
+        end
+      end
+    end
+  end
+end