agent-harness 0.5.7 → 0.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2335caa6b19fc12579028ec7c9796c89e588629c7e076b957cac4c6b563d9fdb
-  data.tar.gz: f7bbe39c811548d1f92262ece7d696d9e8486a93c3d494c7cf397c294f41901e
+  metadata.gz: 93f5a11872f464b3eb9834c849f076d9f393f9e1174bc9824952f4c217c9278f
+  data.tar.gz: 25bbd835fd6739f84597d0d5653443ecd238b0e89f20f5e0b20029cb5d8bb119
 SHA512:
-  metadata.gz: e46f340daf52837fa0ae966b5bb2ce1865338b5b9d20d5901b380696e9fac91f35471ec1ef1512f08cc3305346185dfbfd20c2e4a05c2f7ac7d1b466e9dbc5f5
-  data.tar.gz: f6e5c23023174cabf7609b5bf61bc8d07e0a527fa6cc2b219eb19265c1f917897cd846360513c9819a33b970e4180443f0a98a9bc02746bf5c57bafc5ba16b1c
+  metadata.gz: '081955132b518b5d94498bfeb54ddd7641f1d6968fcb53debf143f7762a666edd40dde6a1369553a42c0dc4985cbff9cb41d7ade8dd727fa80572e7a7293cd2f'
+  data.tar.gz: 0345fc32a87b27ba001ae0a6cd26c5b1cc2765f64d7d81bad025b461182cdb0a814c8cdd031478b4e7dcf8bbe1f6b2638e3814cbf3c9537e038dc8bca1255a1f

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.7"
+  ".": "0.5.8"
 }

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 ## [Unreleased]
 
+## [0.5.8](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.7...agent-harness/v0.5.8) (2026-04-07)
+
+
+### Bug Fixes
+
+* 64: feat(installers): make Claude CLI installation/version support a first-class provider contract ([#78](https://github.com/viamin/agent-harness/issues/78)) ([0d83590](https://github.com/viamin/agent-harness/commit/0d83590dc9bb9bc7c8d621660bcd73b8eb613d43))
+* 70: feat(installers): make Cursor agent CLI installation/version support a first-class provider contract ([#82](https://github.com/viamin/agent-harness/issues/82)) ([483e9be](https://github.com/viamin/agent-harness/commit/483e9be752de9548020135a86170d978d2a23ae8))
+* 71: feat(installers): make Aider CLI installation/version support a first-class provider contract ([#84](https://github.com/viamin/agent-harness/issues/84)) ([3cfcc1c](https://github.com/viamin/agent-harness/commit/3cfcc1cac831060c12fd8a39130ee7bb9b048aa5))
+* 74: feat(providers): expose provider capability/installability/auth metadata for downstream apps ([#88](https://github.com/viamin/agent-harness/issues/88)) ([4f9b3ba](https://github.com/viamin/agent-harness/commit/4f9b3ba6a53c830eaf53e9233e8df38970c52c8c))
+
 ## [0.5.7](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.6...agent-harness/v0.5.7) (2026-04-07)
 
 

data/README.md

@@ -5,7 +5,7 @@ A unified Ruby interface for CLI-based AI coding agents like Claude Code, Cursor
 ## Features
 
 - **Unified Interface**: Single API for multiple AI coding agents
-- **8 Built-in Providers**: Claude Code, Cursor, Gemini CLI, GitHub Copilot, Codex, Aider, OpenCode, Kilocode
+- **9 Built-in Providers**: Claude Code, Cursor, Gemini CLI, GitHub Copilot, Codex, Aider, OpenCode, Kilocode, Mistral Vibe
 - **Full Orchestration**: Provider switching, circuit breakers, rate limiting, and health monitoring
 - **Flexible Configuration**: YAML, Ruby DSL, or environment variables
 - **Token Tracking**: Monitor usage across providers for cost and limit management
@@ -107,6 +107,7 @@ end
 | `:aider` | `aider` | Aider coding assistant |
 | `:opencode` | `opencode` | OpenCode CLI |
 | `:kilocode` | `kilo` | Kilocode CLI |
+| `:mistral_vibe` | `mistral-vibe` | Mistral Vibe CLI |
 
 ### Provider Install Contracts
 
@@ -126,6 +127,41 @@ contract[:install_command]
 # => ["npm", "install", "-g", "--ignore-scripts", "@google/gemini-cli@0.35.3"]
 ```
 
+Cursor also exposes a first-class install contract for container/image builds.
+The contract publishes checksums for both the installer script and the default
+Linux x64 artifact so consumers can verify downloads independently:
+
+```ruby
+cursor_install = AgentHarness::Providers::Cursor.install_metadata
+
+cursor_install
+# => {
+#      source: {
+#        type: :shell_script,
+#        url: "https://cursor.com/install",
+#        resolved_version: "2026.03.30-a5d3e17",
+#        default_artifact_url: "https://downloads.cursor.com/lab/2026.03.30-a5d3e17/linux/x64/agent-cli-package.tar.gz"
+#      },
+#      checksum: {
+#        strategy: :sha256,
+#        targets: {
+#          script: { url: "https://cursor.com/install", value: "8371..." },
+#          artifacts: { "linux/x64" => { url: "https://downloads.cursor.com/...", value: "e0d4..." } }
+#        }
+#      },
+#      binary: {
+#        name: "cursor-agent",
+#        path: "$HOME/.local/bin/cursor-agent",
+#        suggested_global_path: "/usr/local/bin/cursor-agent"
+#      },
+#      version: {
+#        default: "latest",
+#        supported: "latest",
+#        command: ["cursor-agent", "--version"]
+#      }
+#    }
+```
+
 ### Direct Provider Access
 
 ```ruby
@@ -138,11 +174,28 @@ if AgentHarness::Providers::Registry.instance.get(:claude).available?
   puts "Claude CLI is installed"
 end
 
+# Ask the harness which Claude CLI install contract it supports
+contract = AgentHarness.install_contract(:claude)
+puts contract[:install][:command]
+# => "tmp_script=$(mktemp) && ... && bash \"$tmp_script\" 2.1.92"
+puts contract[:install][:post_install_binary_path]
+# => "$HOME/.local/bin/claude"
+puts contract[:supported_versions][:default]
+# => "2.1.92"
+puts contract[:supported_versions][:requirement]
+# => ">= 2.1.92, < 2.2.0"
+
 # List all registered providers
 AgentHarness::Providers::Registry.instance.all
-# => [:claude, :cursor, :gemini, :github_copilot, :codex, :opencode, :kilocode, :aider]
+# => [:claude, :cursor, :gemini, :github_copilot, :codex, :opencode, :kilocode, :aider, :mistral_vibe]
 ```
 
+For Claude, the install contract is the first-class source of truth for:
+
+- the official install recipe the current harness release expects
+- the expected binary name and normalized PATH entry that recipe leaves behind
+- the supported Claude CLI version boundary the current harness release validates (`default` plus the compatible version range)
+
 ### Provider Installation Contracts
 
 Downstream apps can ask `agent-harness` for provider-specific CLI install
@@ -170,6 +223,8 @@ Providers that expose installation contracts can also be queried through the
 generic API:
 
 ```ruby
+codex_install = AgentHarness.installation_contract(:codex)
+aider_install = AgentHarness.installation_contract(:aider)
 opencode_install = AgentHarness.installation_contract(:opencode)
 
 opencode_install
@@ -181,11 +236,94 @@ opencode_install
 #      binary_name: "opencode",
 #      install_command: ["npm", "install", "-g", "--ignore-scripts", "opencode-ai@1.3.2"]
 #    }
+
+aider_install
+# => {
+#      source: :uv_tool,
+#      bootstrap_package: "uv==0.8.17",
+#      package_name: "aider-chat",
+#      version: "0.86.2",
+#      binary_name: "aider",
+#      binary_path: "/usr/local/bin/aider",
+#      install_environment: {
+#        "UV_TOOL_BIN_DIR" => "/usr/local/bin",
+#        "UV_TOOL_DIR" => "/opt/uv/tools",
+#        "UV_PYTHON_INSTALL_DIR" => "/opt/uv/python"
+#      },
+#      bootstrap_commands: [
+#        ["python3", "-m", "pip", "install", "--no-cache-dir", "--break-system-packages", "uv==0.8.17"]
+#      ],
+#      install_command: ["uv", "tool", "install", "--force", "--python", "python3.12", "--with", "pip", "aider-chat==0.86.2"]
+#    }
+```
+
+For supported providers like Codex and Aider, the install contract tracks
+the CLI version supported by the current `agent-harness` release. The
+contract includes bootstrap requirements, install command shape, and the
+expected runtime binary, and the provider specs assert that runtime
+expectations remain aligned with the published install metadata.
+
+### Provider Metadata
+
+Downstream apps can also query a consolidated provider metadata contract for
+configuration UIs and policy decisions.
+
+The following example shows how to retrieve metadata for the Anthropic provider:
+
+```ruby
+metadata = AgentHarness.provider_metadata(:anthropic)
+
+metadata
+# => {
+#      provider: :claude,
+#      canonical_provider: :claude,
+#      aliases: [:anthropic],
+#      auth: {
+#        default_mode: :oauth,
+#        supported_modes: [:oauth],
+#        service: :anthropic,
+#        api_family: :anthropic
+#      },
+#      runtime: {
+#        interface: :cli,
+#        requires_cli: true,
+#        installable: false,
+#        installation: nil,
+#        supports_mcp: true,
+#        supports_dangerous_mode: true
+#      },
+#      health_check: {
+#        supports_registry_checks: true,
+#        auth_check_supported: true,
+#        lightweight: true
+#      },
+#      identity: {
+#        bot_usernames: ["claude", "anthropic"]
+#      }
+#    }
+```
+
+To enumerate the full catalog:
+
+```ruby
+AgentHarness.provider_metadata_catalog
+# => { claude: {...}, cursor: {...}, gemini: {...}, ... }
+```
+
+Provider metadata is cached so repeated catalog reads stay cheap.
+Pass `refresh: true` to rebuild metadata and re-run live availability checks when needed:
+
+```ruby
+AgentHarness.provider_metadata(:anthropic, refresh: true)
+AgentHarness.provider_metadata_catalog(refresh: true)
 ```
 
 For providers with install contracts, the metadata tracks the CLI version
 supported by the current `agent-harness` release, and the runtime adapter
 tests assert that the expected binary remains aligned with that contract.
+`runtime[:installation]` is normalized to a stable shape with
+`source_type`, `package_name`, version fields, and install commands so
+downstream apps do not need provider-specific branching.
 
 ### Custom Providers
 

data/lib/agent_harness/authentication.rb

@@ -94,15 +94,26 @@ module AgentHarness
 
       def resolve_provider(provider_name)
         klass = Providers::Registry.instance.get(provider_name)
-        # Construct the provider with config/executor/logger to match
-        # ProviderManager#create_provider and support custom providers
-        # that may rely on these initializer arguments.
-        config = AgentHarness.configuration.providers[provider_name]
-        klass.new(
-          config: config,
-          executor: AgentHarness.configuration.command_executor,
-          logger: AgentHarness.logger
-        )
+        canonical_name = Providers::Registry.instance.canonical_name(provider_name)
+        config = provider_config_for(provider_name, canonical_name: canonical_name)
+        executor = AgentHarness.configuration.command_executor
+        logger = AgentHarness.logger
+
+        provider = if klass.respond_to?(:build_provider_instance, true)
+          klass.send(:build_provider_instance, config: config, executor: executor, logger: logger)
+        else
+          klass.new(config: config, executor: executor, logger: logger)
+        end
+
+        # Ensure the executor is available even when the provider constructor
+        # accepts only a subset of keywords (e.g. config: only).
+        if provider.respond_to?(:executor=) && provider.executor.nil?
+          provider.executor = executor
+        elsif !provider.respond_to?(:executor)
+          provider.define_singleton_method(:executor) { executor }
+        end
+
+        provider
       rescue ConfigurationError
         raise ProviderNotFoundError, "Unknown provider: #{provider_name}"
       end
@@ -152,6 +163,14 @@ module AgentHarness
         "https://claude.ai/oauth/authorize"
       end
 
+      def provider_config_for(requested_name, canonical_name:)
+        requested_key = requested_name.to_sym
+        canonical_key = canonical_name.to_sym
+
+        AgentHarness.configuration.providers[requested_key] ||
+          AgentHarness.configuration.providers[canonical_key]
+      end
+
       def refresh_claude_auth(token: nil)
         raise ArgumentError, "token must be a non-empty string" unless token.is_a?(String) && !token.strip.empty?
 

data/lib/agent_harness/orchestration/provider_manager.rb

@@ -205,13 +205,25 @@ module AgentHarness
 
       def create_provider(name, executor: @config.command_executor)
         klass = @registry.get(name)
-        config = @config.providers[name]
+        canonical_name = @registry.canonical_name(name)
+        config = provider_config_for(name, canonical_name: canonical_name)
+        logger = AgentHarness.logger
+
+        provider = if klass.respond_to?(:build_provider_instance, true)
+          klass.send(:build_provider_instance, config: config, executor: executor, logger: logger)
+        else
+          klass.new(config: config, executor: executor, logger: logger)
+        end
 
-        klass.new(
-          config: config,
-          executor: executor,
-          logger: AgentHarness.logger
-        )
+        # Ensure the executor is available even when the provider constructor
+        # accepts only a subset of keywords (e.g. config: only).
+        if provider.respond_to?(:executor=) && provider.executor.nil?
+          provider.executor = executor
+        elsif !provider.respond_to?(:executor)
+          provider.define_singleton_method(:executor) { executor }
+        end
+
+        provider
       end
 
       def select_fallback(provider_name, reason:, executor: nil)
@@ -243,6 +255,14 @@ module AgentHarness
         chain += @config.providers.keys
         chain.uniq
       end
+
+      def provider_config_for(requested_name, canonical_name:)
+        requested_key = requested_name.to_sym
+        canonical_key = canonical_name.to_sym
+
+        @config.providers[requested_key] ||
+          @config.providers[canonical_key]
+      end
     end
   end
 end

data/lib/agent_harness/provider_health_check.rb

@@ -431,17 +431,39 @@ module AgentHarness
       end
 
       def build_provider(provider_name, klass, executor:)
-        config = AgentHarness.configuration.providers[provider_name]
-        klass.new(
-          config: config,
-          executor: executor || AgentHarness.configuration.command_executor,
-          logger: AgentHarness.logger
-        )
+        canonical_name = Providers::Registry.instance.canonical_name(provider_name)
+        config = provider_config_for(provider_name, canonical_name: canonical_name)
+        executor ||= AgentHarness.configuration.command_executor
+        logger = AgentHarness.logger
+
+        provider = if klass.respond_to?(:build_provider_instance, true)
+          klass.send(:build_provider_instance, config: config, executor: executor, logger: logger)
+        else
+          klass.new(config: config, executor: executor, logger: logger)
+        end
+
+        # Ensure the executor is available even when the provider constructor
+        # accepts only a subset of keywords (e.g. config: only).
+        if provider.respond_to?(:executor=) && provider.executor.nil?
+          provider.executor = executor
+        elsif !provider.respond_to?(:executor)
+          provider.define_singleton_method(:executor) { executor }
+        end
+
+        provider
       end
 
       def monotonic_now
         Process.clock_gettime(Process::CLOCK_MONOTONIC)
       end
+
+      def provider_config_for(requested_name, canonical_name:)
+        requested_key = requested_name.to_sym
+        canonical_key = canonical_name.to_sym
+
+        AgentHarness.configuration.providers[requested_key] ||
+          AgentHarness.configuration.providers[canonical_key]
+      end
     end
   end
 end