agent-harness 0.30.0 → 0.33.0

data/lib/agent_harness/providers/anthropic.rb

@@ -17,6 +17,14 @@ module AgentHarness
       include RateLimitResetParsing
       include McpConfigFileSupport
 
+      # Anthropic rate-limit response headers exposing quota/rate information.
+      # These are surfaced on normal /v1/messages responses and parsed by
+      # {#update_quota_from_headers} to opportunistically refresh cached quota
+      # without making a dedicated API call.
+      RATE_LIMIT_HEADER_LIMIT = "anthropic-ratelimit-tokens-limit"
+      RATE_LIMIT_HEADER_REMAINING = "anthropic-ratelimit-tokens-remaining"
+      RATE_LIMIT_HEADER_RESET = "anthropic-ratelimit-tokens-reset"
+
       # Model name pattern for Anthropic Claude models
       MODEL_PATTERN = /^claude-[\d.-]+-(?:opus|sonnet|haiku)(?:-\d{8})?$/i
       SUPPORTED_CLI_VERSION = "2.1.92"
@@ -411,6 +419,25 @@ module AgentHarness
 
       def subscription_unset_vars = ["ANTHROPIC_API_KEY", "ANTHROPIC_BASE_URL"] + api_key_unset_vars
 
+      # Opportunistically refresh quota info from Anthropic rate-limit headers
+      # observed on a normal /v1/messages response.
+      #
+      # @param headers [Hash{String=>String}, Net::HTTPHeader] response headers
+      # @return [AgentHarness::QuotaStatus, nil]
+      def update_quota_from_headers(headers)
+        limit_value = header_value(headers, RATE_LIMIT_HEADER_LIMIT)
+        remaining_value = header_value(headers, RATE_LIMIT_HEADER_REMAINING)
+        return nil unless limit_value || remaining_value
+
+        QuotaStatus.new(
+          available: true,
+          remaining: remaining_value&.to_i,
+          limit: limit_value&.to_i,
+          reset_at: parse_rate_limit_header_reset(headers),
+          unit: :tokens
+        )
+      end
+
       def supports_mcp?
         true
       end
@@ -678,6 +705,7 @@ module AgentHarness
         kwargs[:max_tokens] = max_tokens if max_tokens
 
         response = transport.send_message(prompt, **kwargs)
+        response = attach_quota_status_from_headers(response)
 
         # Apply runtime model override if present
         runtime = options[:provider_runtime]
@@ -814,6 +842,26 @@ module AgentHarness
       def log_debug(action, **context)
         @logger&.debug("[AgentHarness::Anthropic] #{action}: #{context.inspect}")
       end
+
+      # Read a header value from either a Net::HTTPHeader or a plain Hash.
+      def header_value(headers, name)
+        return headers[name] || headers[name.to_sym] if headers.respond_to?(:[])
+
+        nil
+      rescue NoMethodError
+        nil
+      end
+
+      # Anthropic's ratelimit reset header is an RFC 3339 timestamp
+      # (e.g. "2026-07-21T05:00:00Z"), per the API docs.
+      def parse_rate_limit_header_reset(headers)
+        raw = header_value(headers, RATE_LIMIT_HEADER_RESET)
+        return nil unless raw
+
+        Time.iso8601(raw.to_s).utc
+      rescue ArgumentError
+        nil
+      end
     end
   end
 end

data/lib/agent_harness/providers/base.rb

@@ -322,6 +322,7 @@ module AgentHarness
           &on_chunk
         )
 
+        response = attach_quota_status_from_headers(response)
         response = apply_extensions_after_response(extension_context, response)
 
         track_tokens(response) if response.tokens
@@ -447,6 +448,39 @@ module AgentHarness
         {healthy: true}
       end
 
+      # Proactively query remaining provider quota for the current billing
+      # period without running a full agent.
+      #
+      # The default implementation reports that quota checking is unavailable
+      # so callers can fall back to {AgentHarness::TokenUsageTracker}. Providers
+      # that expose a usage/quota API override this to return a populated
+      # {QuotaStatus}.
+      #
+      # The +env+ hash carries the same provider credentials and overrides that
+      # {send_message} uses (typically derived from +ProviderRuntime#env+), so
+      # the quota check can reuse the same authentication as a normal run.
+      #
+      # @param env [Hash{String=>String}] request-scoped environment overrides
+      # @param timeout [Numeric] time budget in seconds
+      # @return [AgentHarness::QuotaStatus]
+      def check_quota(env:, timeout: 10)
+        QuotaStatus.unavailable
+      end
+
+      # Opportunistically update cached quota info from rate-limit headers
+      # observed during a normal {send_message} flow.
+      #
+      # Providers that emit +x-ratelimit-*+ style headers should override this
+      # to parse them into a {QuotaStatus} and return it. The base
+      # implementation is a no-op so providers that do not expose headers (or
+      # runs where the information is unavailable) are handled gracefully.
+      #
+      # @param headers [Hash{String=>String}, Net::HTTPHeader] response headers
+      # @return [AgentHarness::QuotaStatus, nil]
+      def update_quota_from_headers(headers)
+        nil
+      end
+
       protected
 
       # Build CLI command - override in subclasses
@@ -1019,6 +1053,29 @@ module AgentHarness
           output_tokens: response.tokens[:output] || 0,
           total_tokens: response.tokens[:total]
         )
+
+        # Feed the same usage into the fallback quota tracker so providers
+        # without a proactive quota API can still estimate remaining quota from
+        # a caller-configured billing limit. The record signatures intentionally
+        # match so the two trackers can share this hook.
+        AgentHarness.token_usage_tracker.record(
+          provider: self.class.provider_name,
+          model: response.model || @config.model,
+          input_tokens: response.tokens[:input] || 0,
+          output_tokens: response.tokens[:output] || 0,
+          total_tokens: response.tokens[:total]
+        )
+      end
+
+      def attach_quota_status_from_headers(response)
+        headers = response.metadata[:headers]
+        return response unless headers
+
+        quota_status = update_quota_from_headers(headers)
+        return response unless quota_status
+
+        response.metadata[:quota_status] = quota_status
+        response
       end
 
       def handle_error(error, prompt:, options:)

data/lib/agent_harness/providers/codex.rb

@@ -661,6 +661,26 @@ module AgentHarness
 
       def cli_env_overrides = {"PAID_CODEX_SUBSCRIPTION_AUTH" => "1"}
 
+      # Proactively check quota for Codex's configured backend.
+      #
+      # Codex runners frequently route through OpenRouter by setting
+      # +OPENAI_BASE_URL=https://openrouter.ai/api/v1+. When the request env
+      # indicates OpenRouter, the check is delegated to
+      # {QuotaCheckers::OpenRouter}, which queries the +/credits+ endpoint.
+      # Otherwise OpenAI's quota API is not publicly exposed, so the check
+      # returns unavailable and callers fall back to {TokenUsageTracker}.
+      #
+      # @param env [Hash{String=>String}] request-scoped environment
+      # @param timeout [Numeric] time budget in seconds
+      # @return [AgentHarness::QuotaStatus]
+      def check_quota(env:, timeout: QuotaCheckers::OpenRouter::DEFAULT_TIMEOUT)
+        if QuotaCheckers::OpenRouter.routes_through_open_router?(env)
+          return QuotaCheckers::OpenRouter.check(env: env, timeout: timeout, logger: @logger)
+        end
+
+        QuotaStatus.unavailable
+      end
+
       def send_message(prompt:, **options)
         super
       ensure

data/lib/agent_harness/providers/kilocode.rb

@@ -10,9 +10,36 @@ module AgentHarness
     # Provides integration with the Kilocode CLI tool.
     class Kilocode < Base
       PACKAGE_NAME = "@kilocode/cli"
-      DEFAULT_VERSION = "7.1.3"
+      DEFAULT_VERSION = "7.4.16"
       SUPPORTED_VERSION_REQUIREMENT = "= #{DEFAULT_VERSION}"
       STRUCTURED_EVENT_TYPES = %w[text error step_finish result usage].freeze
+      MODEL_NAMES = %w[
+        glm-5
+        glm-5.1
+        glm-5.1-free
+        glm-5.1-thinking
+        glm-5.2
+        glm-5.2-fast
+        glm-5.2-flex
+        glm-5.2-free
+        glm-5.2-nitro
+        glm-5.2-short
+        glm-5.2-short-fast
+        glm-5.2-short-fast-flex
+        glm-5.2-short-flex
+        glm-5p1
+        glm-5p1-fast
+        glm-5p2
+        glm-5p2-fast
+        glm-5v-turbo
+      ].freeze
+      MODEL_CATALOG = MODEL_NAMES.map do |name|
+        tier = name.include?("free") ? "free" : "standard"
+        tier = "advanced" if %w[glm-5.1 glm-5.1-thinking glm-5.2 glm-5p1 glm-5p2].include?(name)
+
+        {name: name, family: name, tier: tier, provider: "kilocode"}.freeze
+      end.freeze
+      MODEL_FAMILY_PATTERN = /\Aglm-5(?:[a-z][\w.-]*|[.-][\w.-]+)?\z/i
       # Kilo CLI (an OpenCode fork) ships the same external_directory
       # permission category as OpenCode, defaulting to "ask" for anything
       # outside the project dir. In non-interactive execution there is no
@@ -73,7 +100,20 @@ module AgentHarness
 
         def discover_models
           return [] unless available?
-          []
+
+          MODEL_CATALOG.map(&:dup)
+        end
+
+        def model_family(provider_model_name)
+          provider_model_name.to_s
+        end
+
+        def provider_model_name(family_name)
+          family_name.to_s
+        end
+
+        def supports_model_family?(family_name)
+          MODEL_FAMILY_PATTERN.match?(family_name.to_s)
         end
 
         def installation_contract(version: DEFAULT_VERSION)
@@ -379,23 +419,83 @@ module AgentHarness
 
       private
 
-      # Default-merge a permissive external_directory permission into the
-      # generated Kilo config unless the caller takes responsibility for
-      # permission config. A caller-supplied permission (passed via the
-      # +:permission+ option or already present on the config under the
-      # +"permission"+ key, e.g. from runtime metadata config extras) is
-      # honored verbatim and never overridden, and an invalid or empty
-      # caller permission is ignored in favor of the default rule.
+      # Default-merge the permissive external_directory permission into the
+      # generated Kilo config. A caller that supplies a +permission+ block is
+      # merged ON TOP of the provider's non-interactive defaults (the container
+      # scratch + home-directory allowlist): the default +external_directory+
+      # entries are unioned with the caller's +external_directory+ entries (the
+      # caller wins on conflicting patterns) and any other caller-supplied
+      # permission category is carried through verbatim. This makes it hard to
+      # accidentally discard the provider defaults when a caller only needs to
+      # add a single +external_directory+ entry (see #310).
+      #
+      # A caller that intentionally owns the full permission block (e.g. to deny
+      # the default /tmp or home paths) can opt out of the merge with the
+      # +:permission_replace+ (or +"permission_replace"+) option, in which case
+      # the caller-supplied permission is honored verbatim and no defaults are
+      # injected. If +permission_replace+ is set but the caller does not supply
+      # a +permission+ key at all, the config is left without any injected
+      # +permission+ block.
+      #
+      # An invalid caller permission is ignored in favor of the default rule.
+      # An empty caller permission hash also falls back to the default rule,
+      # unless +permission_replace+ is set, in which case the empty hash is
+      # preserved verbatim.
       def apply_default_external_directory_permission(config, options = {})
+        if options[:permission_replace] || options["permission_replace"]
+          if options.key?(:permission)
+            config["permission"] = deep_dup(options[:permission])
+          elsif options.key?("permission")
+            config["permission"] = deep_dup(options["permission"])
+          else
+            config.delete("permission")
+          end
+          return
+        end
+
         caller_permission = options[:permission] || options["permission"] || config["permission"]
+
         if caller_permission.is_a?(Hash) && !caller_permission.empty?
-          config["permission"] = deep_dup(caller_permission)
+          config["permission"] = merge_default_permission(caller_permission)
           return
         end
 
         config["permission"] = deep_dup(DEFAULT_PERMISSION_CONFIG)
       end
 
+      # Merge a caller-supplied permission block on top of the provider default
+      # permission rule. The default +external_directory+ allowlist is unioned
+      # with the caller's +external_directory+ entries (caller decisions win on
+      # conflicting patterns); every other caller-supplied permission category
+      # is carried through verbatim.
+      def merge_default_permission(caller_permission)
+        merged = deep_dup(DEFAULT_PERMISSION_CONFIG)
+
+        caller_permission.each do |category, rules|
+          if category.to_s == "external_directory"
+            merged["external_directory"] = merge_external_directory_rules(merged["external_directory"], rules)
+          else
+            merged[category.to_s] = deep_dup(rules)
+          end
+        end
+
+        merged
+      end
+
+      # Union default external_directory rules with caller-supplied rules.
+      # Caller decisions win on overlapping patterns. A non-Hash caller value
+      # (e.g. a scalar default) cannot be meaningfully merged, so it is honored
+      # verbatim for that category.
+      def merge_external_directory_rules(default_rules, caller_rules)
+        return deep_dup(caller_rules) unless caller_rules.is_a?(Hash)
+
+        rules = deep_dup(default_rules)
+        caller_rules.each do |pattern, decision|
+          rules[pattern.to_s] = deep_dup(decision)
+        end
+        rules
+      end
+
       def kilocode_config_path
         "~/.config/kilocode/kilo.json"
       end
@@ -410,7 +510,10 @@ module AgentHarness
 
         payload = stringify_keys(config_extras)
         payload["model"] = runtime.model if runtime.model
-        apply_default_external_directory_permission(payload)
+        apply_default_external_directory_permission(payload, payload)
+        # +permission_replace+ is a control flag for the merge above, not a Kilo
+        # config key, so strip it before the payload is serialized to disk.
+        payload.delete("permission_replace")
         payload.empty? ? nil : payload
       end
 

data/lib/agent_harness/providers/opencode.rb

@@ -10,8 +10,8 @@ module AgentHarness
     # Provides integration with the OpenCode CLI tool.
     class Opencode < Base
       CLI_PACKAGE = "opencode-ai"
-      SUPPORTED_CLI_VERSION = "1.3.2"
-      SUPPORTED_CLI_REQUIREMENT = Gem::Requirement.new(">= #{SUPPORTED_CLI_VERSION}", "< 1.4.0").freeze
+      SUPPORTED_CLI_VERSION = "1.18.9"
+      SUPPORTED_CLI_REQUIREMENT = Gem::Requirement.new(">= #{SUPPORTED_CLI_VERSION}", "< 2.0.0").freeze
       INSTALL_COMMAND_PREFIX = ["npm", "install", "-g", "--ignore-scripts"].freeze
       # Allowlist of external_directory patterns auto-approved in
       # non-interactive execution. See the DEFAULT_PERMISSION_RULE comment

data/lib/agent_harness/providers/quota_checkers/open_router.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module AgentHarness
+  module Providers
+    # Standalone quota-check helpers for backends that do not have a dedicated
+    # provider class but can still be queried proactively before a run starts.
+    #
+    # Today this hosts the OpenRouter credits lookup, which Paid's runners can
+    # route through even though there is no canonical +:openrouter+ provider
+    # class (it is selected via +ProviderRuntime#api_provider+). Other backends
+    # that surface through OpenAI-compatible transports but expose their own
+    # balance endpoint belong here too.
+    module QuotaCheckers
+      # Quota checker for OpenRouter's credit balance API.
+      #
+      # OpenRouter is selected by Paid runners via +ProviderRuntime+ overrides
+      # rather than a dedicated provider class, so the check is implemented as
+      # a standalone helper that any provider can call from its own
+      # +check_quota+ implementation when the request env points at OpenRouter.
+      #
+      # @example Direct usage
+      #   AgentHarness::Providers::QuotaCheckers::OpenRouter.check(
+      #     env: { "OPENROUTER_API_KEY" => "sk-..." }
+      #   )
+      #   # => #<AgentHarness::QuotaStatus available=true remaining=12.5 unit=:credits ...>
+      module OpenRouter
+        DEFAULT_BASE_URL = "https://openrouter.ai/api/v1"
+        DEFAULT_TIMEOUT = 10
+        USER_AGENT = "AgentHarness/1.0"
+        HOST_FRAGMENT = "openrouter.ai"
+
+        class << self
+          # Detect whether a request env would route through OpenRouter.
+          #
+          # Used by providers (Codex, Kilocode, etc.) to decide whether to
+          # delegate +check_quota+ to this checker.
+          #
+          # @param env [Hash{String=>String}] request-scoped environment
+          # @return [Boolean]
+          def routes_through_open_router?(env)
+            return false if env.nil?
+
+            values = env.values_at("OPENROUTER_API_KEY", :OPENROUTER_API_KEY)
+            return true if values.any? { |value| value.respond_to?(:to_str) && !value.to_str.empty? }
+
+            base_url_values = env.values_at("OPENAI_BASE_URL", :OPENAI_BASE_URL)
+            base_url_values.any? { |value| value.to_s.include?(HOST_FRAGMENT) }
+          end
+
+          # Resolve the API key the OpenRouter quota endpoint should use.
+          #
+          # Order of precedence: explicit +OPENROUTER_API_KEY+, then
+          # +OPENAI_API_KEY+ (since OpenRouter accepts it under that name when
+          # routed via the OpenAI-compatible transport).
+          #
+          # @param env [Hash{String=>String}] request-scoped environment
+          # @return [String, nil]
+          def resolve_api_key(env)
+            env_value(env, "OPENROUTER_API_KEY") ||
+              env_value(env, "OPENAI_API_KEY")
+          end
+
+          # Query OpenRouter's +/credits+ endpoint and return a {QuotaStatus}.
+          #
+          # @param env [Hash{String=>String}] request-scoped environment
+          # @param base_url [String, nil] override the API base URL
+          # @param timeout [Numeric] time budget in seconds
+          # @param logger [Logger, nil]
+          # @return [AgentHarness::QuotaStatus] populated when credentials are
+          #   present and the API responds; unavailable otherwise
+          def check(env:, base_url: nil, timeout: DEFAULT_TIMEOUT, logger: nil)
+            api_key = resolve_api_key(env)
+            unless api_key && !api_key.empty?
+              logger&.debug("[AgentHarness::QuotaCheckers::OpenRouter] no API key present in env")
+              return QuotaStatus.unavailable
+            end
+
+            uri = URI.parse("#{resolve_base_url(env, base_url)}/credits")
+            response = perform_get(uri:, api_key:, timeout:, logger:)
+            return QuotaStatus.unavailable unless response
+
+            parse_credits_response(response)
+          rescue IOError, SocketError, SystemCallError, Timeout::Error, JSON::ParserError,
+            OpenSSL::SSL::SSLError => e
+            logger&.warn("[AgentHarness::QuotaCheckers::OpenRouter] credit check failed: #{e.message}")
+            QuotaStatus.unavailable
+          end
+
+          private
+
+          def resolve_base_url(env, override)
+            base = override || env_value(env, "OPENROUTER_BASE_URL") || DEFAULT_BASE_URL
+            base.to_s.chomp("/")
+          end
+
+          def env_value(env, key)
+            return nil if env.nil?
+
+            env[key] || env[key.to_sym]
+          end
+
+          def perform_get(uri:, api_key:, timeout:, logger:)
+            http = Net::HTTP.new(uri.host, uri.port)
+            http.use_ssl = (uri.scheme == "https")
+            http.open_timeout = timeout
+            http.read_timeout = timeout
+
+            request = Net::HTTP::Get.new(uri)
+            request["Authorization"] = "Bearer #{api_key}"
+            request["User-Agent"] = USER_AGENT
+
+            logger&.debug("[AgentHarness::QuotaCheckers::OpenRouter] GET #{uri}")
+
+            response = http.request(request)
+            return response if response.is_a?(Net::HTTPSuccess)
+
+            logger&.warn("[AgentHarness::QuotaCheckers::OpenRouter] #{uri} returned HTTP #{response.code}")
+            nil
+          end
+
+          # OpenRouter returns: {"data": {"total_credits": 20.0, "total_usage": 7.5}}
+          def parse_credits_response(response)
+            body = response.body
+            return QuotaStatus.unavailable if body.nil? || body.empty?
+
+            parsed = JSON.parse(body)
+            data = parsed.is_a?(Hash) ? parsed["data"] : nil
+            return QuotaStatus.unavailable unless data.is_a?(Hash)
+
+            total = data["total_credits"]
+            usage = data["total_usage"]
+            return QuotaStatus.unavailable if total.nil? || usage.nil?
+
+            limit = total.to_f
+            used = usage.to_f
+            remaining = limit - used
+
+            QuotaStatus.new(
+              available: true,
+              remaining: remaining,
+              limit: limit,
+              reset_at: nil,
+              unit: :credits
+            )
+          end
+        end
+      end
+    end
+  end
+end

data/lib/agent_harness/providers/quota_checkers.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "quota_checkers/open_router"

data/lib/agent_harness/quota_status.rb

@@ -0,0 +1,175 @@
+# frozen_string_literal: true
+
+require "time"
+
+module AgentHarness
+  # Serializable snapshot of a provider's remaining quota for the current
+  # billing period.
+  #
+  # {QuotaStatus} is the unified return type for {Providers::Base#check_quota}
+  # and {TokenUsageTracker#estimated_usage}. It lets the orchestration layer
+  # compare runners on the same axis (remaining/limit/unit) so Paid can
+  # auto-balance weights and let multiple runners exhaust their quotas at
+  # roughly the same rate.
+  #
+  # All instances are frozen so callers can safely cache, share, and persist
+  # them (for example, to a database column) without worrying about mutation.
+  #
+  # @example A real API-backed status
+  #   AgentHarness::QuotaStatus.new(
+  #     available: true,
+  #     remaining: 1_500_000,
+  #     limit: 2_000_000,
+  #     reset_at: Time.utc(2026, 8, 1),
+  #     unit: :tokens
+  #   )
+  #
+  # @example Sentinel returned by providers that do not expose a quota API
+  #   AgentHarness::QuotaStatus.unavailable
+  #
+  class QuotaStatus < Struct.new(
+    :available,
+    :remaining,
+    :limit,
+    :reset_at,
+    :unit,
+    :checked_at
+  )
+    # Units recognized by the harness. Providers may return other Symbols,
+    # but the documented set is enumerated here so callers can switch on it
+    # without typos. New units should be added here when a provider exposes
+    # one that does not fit an existing bucket.
+    UNITS = %i[
+      tokens
+      requests
+      credits
+      cost_cents
+    ].freeze
+
+    def initialize(available: false, remaining: nil, limit: nil, reset_at: nil, unit: nil, checked_at: nil)
+      unless reset_at.nil? || reset_at.is_a?(Time)
+        raise ArgumentError, "reset_at must be a Time or nil (got #{reset_at.class})"
+      end
+      unless unit.nil? || unit.is_a?(Symbol)
+        raise ArgumentError, "unit must be a Symbol or nil (got #{unit.class})"
+      end
+      unless available == true || available == false
+        raise ArgumentError, "available must be a boolean (got #{available.class})"
+      end
+
+      # Snap the check time when an available status is built without one so
+      # cached/stored statuses always record when the underlying lookup ran.
+      resolved_checked_at = checked_at || (available ? Time.now.utc : nil)
+
+      super(
+        available: available,
+        remaining: remaining,
+        limit: limit,
+        reset_at: reset_at,
+        unit: unit,
+        checked_at: resolved_checked_at
+      )
+      freeze
+    end
+
+    # Whether this provider exposes any quota information at all.
+    #
+    # @return [Boolean]
+    def available? = available == true
+
+    # Whether the tracked quota is exhausted. Returns false when availability
+    # is unknown so callers can treat the status conservatively.
+    #
+    # @return [Boolean]
+    def exhausted?
+      return false unless available?
+      return false if remaining.nil?
+
+      remaining <= 0
+    end
+
+    # Human-friendly label for the +unit+ value, useful for logs and UIs.
+    #
+    # @return [String]
+    def unit_label
+      return "unknown" if unit.nil?
+
+      unit.to_s
+    end
+
+    # Serializable hash suitable for database persistence.
+    #
+    # +reset_at+ and +checked_at+ are serialized as ISO8601 strings in UTC so
+    # the hash round-trips through JSON without losing timezone information.
+    #
+    # @return [Hash{Symbol => Object}]
+    def to_h
+      {
+        available: available,
+        remaining: remaining,
+        limit: limit,
+        reset_at: serialize_time(reset_at),
+        unit: unit,
+        checked_at: serialize_time(checked_at)
+      }
+    end
+
+    # Build a QuotaStatus from a Hash produced by {#to_h}.
+    #
+    # @param hash [Hash] serialized QuotaStatus
+    # @return [QuotaStatus]
+    def self.from_h(hash)
+      return unavailable if hash.nil? || hash.empty?
+
+      new(
+        available: fetch_value(hash, :available),
+        remaining: fetch_value(hash, :remaining),
+        limit: fetch_value(hash, :limit),
+        reset_at: parse_time(fetch_value(hash, :reset_at)),
+        unit: normalize_unit(fetch_value(hash, :unit)),
+        checked_at: parse_time(fetch_value(hash, :checked_at))
+      )
+    end
+
+    def self.fetch_value(hash, key)
+      symbol_value = hash[key]
+      return symbol_value unless symbol_value.nil?
+
+      hash[key.to_s]
+    end
+    private_class_method :fetch_value
+
+    # Sentinel for "this provider does not expose a quota API." The default
+    # implementation of {Providers::Base#check_quota} returns this so callers
+    # can treat all providers uniformly.
+    #
+    # @return [QuotaStatus]
+    def self.unavailable
+      new(available: false)
+    end
+
+    def self.normalize_unit(value)
+      return nil if value.nil?
+
+      value.to_sym
+    end
+    private_class_method :normalize_unit
+
+    def self.parse_time(value)
+      return nil if value.nil?
+
+      Time.parse(value).utc
+    rescue ArgumentError
+      nil
+    end
+    private_class_method :parse_time
+
+    private
+
+    def serialize_time(value)
+      return nil unless value.is_a?(Time)
+
+      value.utc.iso8601
+    end
+  end
+end