agent-harness 0.5.7 → 0.5.8

data/lib/agent_harness/providers/registry.rb

@@ -17,10 +17,32 @@ module AgentHarness
     class Registry
       include Singleton
 
+      BUILTIN_PROVIDER_DEFINITIONS = [
+        {name: :claude, require_path: "agent_harness/providers/anthropic", class_name: :Anthropic, aliases: [:anthropic]},
+        {name: :cursor, require_path: "agent_harness/providers/cursor", class_name: :Cursor, aliases: []},
+        {name: :gemini, require_path: "agent_harness/providers/gemini", class_name: :Gemini, aliases: []},
+        {
+          name: :github_copilot,
+          require_path: "agent_harness/providers/github_copilot",
+          class_name: :GithubCopilot,
+          aliases: [:copilot]
+        },
+        {name: :codex, require_path: "agent_harness/providers/codex", class_name: :Codex, aliases: []},
+        {name: :opencode, require_path: "agent_harness/providers/opencode", class_name: :Opencode, aliases: []},
+        {name: :kilocode, require_path: "agent_harness/providers/kilocode", class_name: :Kilocode, aliases: []},
+        {name: :aider, require_path: "agent_harness/providers/aider", class_name: :Aider, aliases: []},
+        {name: :mistral_vibe, require_path: "agent_harness/providers/mistral_vibe", class_name: :MistralVibe, aliases: []}
+      ].freeze
+
       def initialize
         @providers = {}
         @aliases = {}
+        @provider_aliases = Hash.new { |hash, key| hash[key] = [] }
+        @metadata_runtime_available = {}
+        @provider_metadata_cache = {}
+        @provider_metadata_catalog_cache = nil
         @builtin_registered = false
+        @builtin_registration_in_progress = false
       end
 
       # Register a provider class
@@ -32,11 +54,32 @@ module AgentHarness
       def register(name, klass, aliases: [])
         name = name.to_sym
         validate_provider_class!(klass)
+        normalized_aliases = aliases
+          .filter_map do |alias_name|
+            normalized_alias = alias_name.to_s.strip
+            next if normalized_alias.empty?
+
+            normalized_alias.to_sym
+          end
+          .uniq - [name]
+
+        validate_provider_name!(name)
+        validate_aliases!(name, normalized_aliases)
+        unregister_aliases_for(name)
 
         @providers[name] = klass
+        @provider_aliases[name] = normalized_aliases
+        @metadata_runtime_available.delete(name)
+        clear_registry_metadata_cache!
+        clear_metadata_caches!(klass)
+
+        normalized_aliases.each do |alias_name|
+          previous_owner = @aliases[alias_name]
+          if previous_owner && previous_owner != name
+            @provider_aliases[previous_owner] = @provider_aliases[previous_owner] - [alias_name]
+          end
 
-        aliases.each do |alias_name|
-          @aliases[alias_name.to_sym] = name
+          @aliases[alias_name] = name
         end
 
         AgentHarness.logger&.debug("[AgentHarness::Registry] Registered provider: #{name}")
@@ -63,6 +106,15 @@ module AgentHarness
         @providers.key?(name)
       end
 
+      # Resolve a provider lookup key to its canonical registered name.
+      #
+      # @param name [Symbol, String] the provider name or alias
+      # @return [Symbol] canonical provider name
+      def canonical_name(name)
+        ensure_builtin_providers_registered
+        resolve_alias(name.to_sym)
+      end
+
       # List all registered provider names
       #
       # @return [Array<Symbol>] provider names
@@ -79,6 +131,27 @@ module AgentHarness
         @providers.select { |_, klass| klass.available? }.keys
       end
 
+      # Fetch install contract metadata for a provider.
+      #
+      # @param name [Symbol, String] the provider name
+      # @return [Hash] the provider install contract
+      # @raise [ConfigurationError] if the provider does not expose an
+      #   install contract
+      def install_contract(name)
+        provider_class = get(name)
+
+        unless provider_class.respond_to?(:install_contract)
+          raise ConfigurationError, "Provider #{provider_class} does not implement .install_contract"
+        end
+
+        contract = provider_class.install_contract
+        unless contract
+          raise ConfigurationError, "Provider #{provider_class} does not expose an install contract"
+        end
+
+        contract
+      end
+
       # Fetch installation metadata for a provider.
       #
       # @param name [Symbol, String] the provider name
@@ -133,30 +206,315 @@ module AgentHarness
         end
       end
 
-      # Reset registry (useful for testing)
+      # Fetch consolidated provider metadata for a provider.
       #
-      # @return [void]
+      # @param name [Symbol, String] the provider name or alias
+      # @return [Hash] provider metadata
+      # @raise [ConfigurationError] if provider not found
+      def provider_metadata(name, refresh: false)
+        ensure_builtin_providers_registered
+
+        requested_name = name.to_sym
+        canonical_name = resolve_alias(requested_name)
+        cache_key = [requested_name, canonical_name]
+
+        return duplicate_metadata(@provider_metadata_cache[cache_key]) if !refresh && @provider_metadata_cache.key?(cache_key)
+
+        refresh_provider_metadata_cache!(requested_name, canonical_name, refresh: refresh)
+      end
+
+      # Get consolidated metadata for all registered providers.
+      #
+      # @param refresh [Boolean] when true, refresh live runtime metadata such
+      #   as CLI availability instead of reusing cached values
+      # @return [Hash<Symbol, Hash>] provider metadata keyed by canonical provider
+      def provider_metadata_catalog(refresh: false)
+        ensure_builtin_providers_registered
+
+        return duplicate_metadata(@provider_metadata_catalog_cache) if !refresh && @provider_metadata_catalog_cache
+
+        if refresh
+          clear_registry_metadata_cache!
+          clear_all_auth_status_metadata_caches!
+        end
+
+        catalog = @providers.keys.each_with_object({}) do |name, result|
+          result[name] = refresh_provider_metadata_cache!(
+            name,
+            name,
+            refresh: refresh,
+            invalidate_provider_cache: false,
+            invalidate_catalog: false
+          )
+        end
+
+        @provider_metadata_catalog_cache = duplicate_metadata(catalog)
+        duplicate_metadata(catalog)
+      end
+
       def reset!
+        @providers.each_value { |klass| clear_metadata_caches!(klass) }
         @providers.clear
         @aliases.clear
+        @provider_aliases.clear
+        @metadata_runtime_available.clear
+        clear_registry_metadata_cache!
         @builtin_registered = false
+        @builtin_registration_in_progress = false
       end
 
       private
 
+      def clear_registry_metadata_cache!
+        @provider_metadata_cache.clear
+        @provider_metadata_catalog_cache = nil
+      end
+
+      def invalidate_provider_metadata_cache!(canonical_name)
+        @provider_metadata_cache.delete_if do |(_, cached_canonical_name), _|
+          cached_canonical_name == canonical_name
+        end
+      end
+
+      def duplicate_metadata(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, nested_value), copy|
+            copy[key] = duplicate_metadata(nested_value)
+          end
+        when Array
+          value.map { |nested_value| duplicate_metadata(nested_value) }
+        when String
+          value.dup
+        else
+          value
+        end
+      end
+
       def resolve_alias(name)
         @aliases[name] || name
       end
 
+      def unregister_aliases_for(name)
+        previous_aliases = @provider_aliases[name]
+        return if previous_aliases.nil? || previous_aliases.empty?
+
+        previous_aliases.each do |alias_name|
+          @aliases.delete(alias_name)
+        end
+      end
+
+      def clear_metadata_caches!(klass)
+        clear_class_metadata_cache!(klass, :@metadata_runtime_available)
+        clear_class_metadata_cache!(klass, :@auth_status_available)
+      end
+
+      def clear_all_auth_status_metadata_caches!
+        @providers.each_value { |klass| clear_class_auth_status_metadata_cache!(klass) }
+      end
+
+      def clear_class_auth_status_metadata_cache!(klass, canonical_name = nil)
+        return unless klass.instance_variable_defined?(:@auth_status_available)
+
+        return clear_class_metadata_cache!(klass, :@auth_status_available) unless canonical_name
+
+        auth_status_cache = klass.instance_variable_get(:@auth_status_available)
+        auth_status_cache.delete_if do |(_requested_name, cached_canonical_name), _|
+          cached_canonical_name == canonical_name
+        end
+      end
+
+      def build_provider_metadata(requested_name, canonical_name, refresh:)
+        klass = @providers[canonical_name] || raise(ConfigurationError, "Unknown provider: #{canonical_name}")
+        aliases = @provider_aliases[canonical_name]
+
+        if klass.respond_to?(:provider_metadata)
+          klass.provider_metadata(
+            aliases: aliases,
+            refresh: refresh,
+            requested_name: requested_name,
+            canonical_name: canonical_name
+          )
+        else
+          fallback_provider_metadata(canonical_name, klass, aliases, refresh: refresh)
+        end
+      end
+
+      def refresh_provider_metadata_cache!(
+        requested_name,
+        canonical_name,
+        refresh:,
+        invalidate_provider_cache: refresh,
+        invalidate_catalog: true
+      )
+        cache_key = [requested_name, canonical_name]
+        invalidate_provider_metadata_cache!(canonical_name) if invalidate_provider_cache
+        klass = @providers[canonical_name]
+        clear_class_auth_status_metadata_cache!(klass, canonical_name) if refresh && klass
+        @provider_metadata_catalog_cache = nil if refresh && invalidate_catalog
+
+        metadata = build_provider_metadata(requested_name, canonical_name, refresh: refresh)
+        @provider_metadata_cache[cache_key] = duplicate_metadata(metadata)
+        duplicate_metadata(metadata)
+      end
+
+      def clear_class_metadata_cache!(klass, ivar_name)
+        return unless klass.instance_variable_defined?(ivar_name)
+
+        klass.remove_instance_variable(ivar_name)
+      end
+
       def validate_provider_class!(klass)
         includes_adapter = klass.include?(Adapter)
         has_required_methods = klass.respond_to?(:provider_name) &&
           klass.respond_to?(:available?) &&
           klass.respond_to?(:binary_name)
 
-        return if includes_adapter || has_required_methods
+        return if includes_adapter
+        return if has_required_methods
+
+        raise ConfigurationError,
+          "Provider class must include AgentHarness::Providers::Adapter or implement required class methods"
+      end
+
+      def validate_provider_name!(name)
+        # Reject canonical provider names that match a builtin canonical name
+        # (e.g. :claude, :gemini). Authentication hardcodes routing for names
+        # like :claude/:anthropic to provider-specific OAuth file handling, so
+        # registering a non-builtin provider under those names yields incorrect
+        # auth behavior at runtime.
+        if builtin_provider_name?(name) && !@builtin_registration_in_progress
+          raise ConfigurationError,
+            "Provider name #{name.inspect} is reserved as a builtin canonical provider"
+        end
+
+        # Reject canonical provider names that match a reserved builtin alias
+        # (e.g. :anthropic is an alias for :claude).
+        builtin_alias_owner = reserved_builtin_alias_owner(name)
+        if builtin_alias_owner && !@builtin_registration_in_progress
+          raise ConfigurationError,
+            "Provider name #{name.inspect} is reserved as a builtin alias for #{builtin_alias_owner.inspect}"
+        end
+
+        conflicting_provider = @aliases[name]
+        return unless conflicting_provider && conflicting_provider != name
+
+        raise ConfigurationError, "Provider #{name.inspect} conflicts with registered alias for #{conflicting_provider.inspect}"
+      end
+
+      def validate_aliases!(name, aliases)
+        conflicting_alias = aliases.find do |alias_name|
+          next false if alias_name == name
+          next true if builtin_provider_name?(alias_name)
+
+          # Reject aliases that match a reserved builtin alias (e.g. :anthropic
+          # for :claude) unless the registering provider is the owning builtin.
+          # Authentication hardcodes routing for these names, so allowing a
+          # custom provider to claim them would cause auth_status/auth_url to
+          # hit the wrong provider.
+          alias_owner = reserved_builtin_alias_owner(alias_name)
+          next true if alias_owner && alias_owner != name
 
-        raise ConfigurationError, "Provider class must include AgentHarness::Providers::Adapter or implement required class methods"
+          @providers.key?(alias_name) ||
+            (@aliases.key?(alias_name) && @aliases[alias_name] != name)
+        end
+        return unless conflicting_alias
+
+        builtin_alias_owner = reserved_builtin_alias_owner(conflicting_alias)
+        owner = if builtin_alias_owner
+          builtin_alias_owner
+        elsif @providers.key?(conflicting_alias)
+          conflicting_alias
+        elsif builtin_provider_name?(conflicting_alias)
+          :builtin_provider
+        else
+          @aliases[conflicting_alias]
+        end
+        raise ConfigurationError, "Alias #{conflicting_alias.inspect} conflicts with registered provider #{owner.inspect}"
+      end
+
+      def builtin_provider_name?(name)
+        BUILTIN_PROVIDER_DEFINITIONS.any? { |definition| definition[:name] == name }
+      end
+
+      def reserved_builtin_alias_owner(name)
+        definition = BUILTIN_PROVIDER_DEFINITIONS.find do |defn|
+          defn[:aliases].include?(name) && defn[:name] != name
+        end
+        definition&.dig(:name)
+      end
+
+      def fallback_provider_metadata(name, klass, aliases, refresh: false)
+        normalized_aliases = aliases
+          .filter_map do |alias_name|
+            normalized_alias = alias_name.to_s.strip
+            next if normalized_alias.empty?
+
+            normalized_alias.to_sym
+          end
+          .uniq
+          .reject { |alias_name| alias_name == name }
+        installation = if klass.respond_to?(:installation_contract)
+          Adapter.normalize_metadata_installation(
+            klass.installation_contract,
+            provider_name: name,
+            binary_name: klass.binary_name
+          )
+        end
+
+        {
+          provider: name,
+          canonical_provider: name,
+          aliases: normalized_aliases,
+          display_name: name.to_s.split("_").map(&:capitalize).join(" "),
+          binary_name: klass.binary_name,
+          auth: {
+            default_mode: nil,
+            supported_modes: [],
+            service: nil,
+            api_family: nil
+          },
+          runtime: {
+            interface: :cli,
+            requires_cli: true,
+            available: metadata_runtime_available(name, klass, refresh: refresh),
+            installable: !installation.nil?,
+            installation: installation,
+            prompt_delivery: nil,
+            output_format: nil,
+            sandbox_aware: nil,
+            uses_subcommand: nil,
+            supports_mcp: false,
+            supported_mcp_transports: [],
+            supports_sessions: false,
+            supports_dangerous_mode: false
+          },
+          configuration: {fields: [], auth_modes: [], openai_compatible: false},
+          capabilities: {streaming: false, file_upload: false, vision: false, tool_use: false, json_mode: false, mcp: false, dangerous_mode: false},
+          health_check: {
+            supports_registry_checks: false,
+            auth_check_supported: false,
+            provider_status: false,
+            configuration_validation: false,
+            lightweight: false
+          },
+          identity: {
+            bot_usernames: [name, *normalized_aliases]
+              .filter_map do |identity|
+                normalized_identity = identity.to_s.strip
+                normalized_identity unless normalized_identity.empty?
+              end
+              .uniq
+          }
+        }
+      end
+
+      def metadata_runtime_available(name, klass, refresh: false)
+        if refresh || !@metadata_runtime_available.key?(name)
+          @metadata_runtime_available[name] = klass.available?
+        end
+
+        @metadata_runtime_available[name]
       end
 
       def ensure_builtin_providers_registered
@@ -167,26 +525,42 @@ module AgentHarness
       end
 
       def register_builtin_providers
-        # Only register providers that exist
-        # These will be loaded on demand
-        register_if_available(:claude, "agent_harness/providers/anthropic", :Anthropic, aliases: [:anthropic])
-        register_if_available(:cursor, "agent_harness/providers/cursor", :Cursor)
-        register_if_available(:gemini, "agent_harness/providers/gemini", :Gemini)
-        register_if_available(:github_copilot, "agent_harness/providers/github_copilot", :GithubCopilot, aliases: [:copilot])
-        register_if_available(:codex, "agent_harness/providers/codex", :Codex)
-        register_if_available(:opencode, "agent_harness/providers/opencode", :Opencode)
-        register_if_available(:kilocode, "agent_harness/providers/kilocode", :Kilocode)
-        register_if_available(:aider, "agent_harness/providers/aider", :Aider)
-        register_if_available(:mistral_vibe, "agent_harness/providers/mistral_vibe", :MistralVibe)
+        @builtin_registration_in_progress = true
+        BUILTIN_PROVIDER_DEFINITIONS.each do |definition|
+          definition_name = definition[:name]
+          next if builtin_provider_name_taken?(definition_name)
+
+          register_if_available(
+            definition_name,
+            definition[:require_path],
+            definition[:class_name],
+            aliases: definition[:aliases]
+          )
+        end
+      ensure
+        @builtin_registration_in_progress = false
+      end
+
+      def builtin_provider_name_taken?(name)
+        @providers.key?(name)
       end
 
       def register_if_available(name, require_path, class_name, aliases: [])
         require_relative require_path.sub("agent_harness/providers/", "")
         klass = AgentHarness::Providers.const_get(class_name)
-        register(name, klass, aliases: aliases)
+        register(name, klass, aliases: builtin_aliases_for(name, aliases))
       rescue LoadError, NameError => e
         AgentHarness.logger&.debug("[AgentHarness::Registry] Provider #{name} not available: #{e.message}")
       end
+
+      def builtin_aliases_for(name, aliases)
+        Array(aliases).reject do |alias_name|
+          alias_key = alias_name.to_sym
+          next false if alias_key == name
+
+          @providers.key?(alias_key) || @aliases.key?(alias_key)
+        end
+      end
     end
   end
 end

data/lib/agent_harness/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentHarness
-  VERSION = "0.5.7"
+  VERSION = "0.5.8"
 end

data/lib/agent_harness.rb

@@ -84,6 +84,14 @@ module AgentHarness
       conductor.provider_manager.get_provider(name)
     end
 
+    # Get install contract metadata for a provider
+    # @param name [Symbol, String] the provider name
+    # @return [Hash] install contract metadata
+    # @raise [ConfigurationError] if the provider does not expose an install contract
+    def install_contract(name)
+      Providers::Registry.instance.install_contract(name)
+    end
+
     # Returns install metadata for a provider CLI when the provider exposes it.
     #
     # @param provider_name [Symbol, String] the provider name
@@ -118,6 +126,26 @@ module AgentHarness
       Providers::Registry.instance.installation_contracts
     end
 
+    # Get consolidated metadata for a provider.
+    #
+    # @param provider_name [Symbol, String] the provider name or alias
+    # @param refresh [Boolean] when true, refresh live runtime metadata such as
+    #   CLI availability instead of reusing cached values
+    # @return [Hash] provider metadata
+    # @raise [ConfigurationError] if the provider name is not registered
+    def provider_metadata(provider_name, refresh: false)
+      Providers::Registry.instance.provider_metadata(provider_name, refresh: refresh)
+    end
+
+    # Get consolidated metadata for all registered providers.
+    #
+    # @param refresh [Boolean] when true, refresh live runtime metadata such as
+    #   CLI availability instead of reusing cached values
+    # @return [Hash<Symbol, Hash>] provider metadata keyed by canonical provider
+    def provider_metadata_catalog(refresh: false)
+      Providers::Registry.instance.provider_metadata_catalog(refresh: refresh)
+    end
+
     # Get smoke-test metadata for a provider CLI when the provider exposes it.
     #
     # @param provider_name [Symbol, String] the provider name

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.5.7
+  version: 0.5.8
 platform: ruby
 authors:
 - Bart Agapinan