agent-harness 0.5.6 → 0.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 946d7c425aff8c96536bc30def7e0abdba7ff7d82020f4941674a8c93be63526
-  data.tar.gz: ffc9d707f89ab60bf9cc59b4e5ccbcd2570a3aaa07e97c5a10bfb731f5dc07a0
+  metadata.gz: 93f5a11872f464b3eb9834c849f076d9f393f9e1174bc9824952f4c217c9278f
+  data.tar.gz: 25bbd835fd6739f84597d0d5653443ecd238b0e89f20f5e0b20029cb5d8bb119
 SHA512:
-  metadata.gz: c7b0dcef83c7a31be09a87884211a8ba03c0c93fb845e666423cd17eb70a358dd122db7e57ce04271fa5e114013adbc0007394211286c23b03cfa6a2a600c68f
-  data.tar.gz: a8f14eb24039afd0a93ec1eb064b59ebbe6d03aafd61ab1859c64729d2253140afebacc5c8ee761578337c671c074425784c33676808534cdf7b8ad809a2df32
+  metadata.gz: '081955132b518b5d94498bfeb54ddd7641f1d6968fcb53debf143f7762a666edd40dde6a1369553a42c0dc4985cbff9cb41d7ade8dd727fa80572e7a7293cd2f'
+  data.tar.gz: 0345fc32a87b27ba001ae0a6cd26c5b1cc2765f64d7d81bad025b461182cdb0a814c8cdd031478b4e7dcf8bbe1f6b2638e3814cbf3c9537e038dc8bca1255a1f

data/.release-please-manifest.json

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

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 ## [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)
+
+
+### Bug Fixes
+
+* 59: fix(codex): replace invalid '--sandbox none' for externally sandboxed runs ([#89](https://github.com/viamin/agent-harness/issues/89)) ([6b0fac5](https://github.com/viamin/agent-harness/commit/6b0fac5e9b83c70c3a55004d9c5ad354a6d3dced))
+* 60: feat: support per-request executor overrides for orchestrated send_message ([#87](https://github.com/viamin/agent-harness/issues/87)) ([7711770](https://github.com/viamin/agent-harness/commit/7711770ab3c9a6659171df1033038acf08b8d5a9))
+* 61: feat: support idle-timeout and streaming execution hooks for long-running provider runs ([#90](https://github.com/viamin/agent-harness/issues/90)) ([adf7558](https://github.com/viamin/agent-harness/commit/adf75583994f78af9d6f5b44eba729b616b46f02))
+* 62: feat: support per-request environment unsets for provider execution ([#76](https://github.com/viamin/agent-harness/issues/76)) ([2dfdb8e](https://github.com/viamin/agent-harness/commit/2dfdb8e6138f21ca0dd1a9e0b2d7cc17d1776612))
+* 63: fix(copilot): align GithubCopilot provider with a real installable CLI contract ([#75](https://github.com/viamin/agent-harness/issues/75)) ([9e585e7](https://github.com/viamin/agent-harness/commit/9e585e79252ac8431fb99bc16bc9ebbecb83439e))
+* 65: feat(installers): make Codex CLI installation/version support a first-class provider contract ([#79](https://github.com/viamin/agent-harness/issues/79)) ([a3f5849](https://github.com/viamin/agent-harness/commit/a3f5849db1bcfa162af98fa5339cf8b8f5314920))
+* 66: feat(installers): make Gemini CLI installation/version support a first-class provider contract ([#80](https://github.com/viamin/agent-harness/issues/80)) ([e349ab6](https://github.com/viamin/agent-harness/commit/e349ab64601cb2fe9bafb488e6b4f96fbcbf012b))
+* 67: feat(installers): make Kilocode CLI installation/version support a first-class provider contract ([#81](https://github.com/viamin/agent-harness/issues/81)) ([547baf5](https://github.com/viamin/agent-harness/commit/547baf5be93939a00cdac1e3d17824eb6dbfb324))
+* 68: feat(installers): make OpenCode CLI installation/version support a first-class provider contract ([#83](https://github.com/viamin/agent-harness/issues/83)) ([21caaf4](https://github.com/viamin/agent-harness/commit/21caaf4e003c41a7fa127e7244c4a61abad7f1cb))
+* 72: feat(providers): add first-class smoke-test/health-check execution contracts for CLI providers ([#85](https://github.com/viamin/agent-harness/issues/85)) ([7c0db3a](https://github.com/viamin/agent-harness/commit/7c0db3a5aa93e62e38240821dfb00b489ad3793b))
+
 ## [0.5.6](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.5...agent-harness/v0.5.6) (2026-03-30)
 
 

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
@@ -106,7 +106,61 @@ end
 | `:codex` | `codex` | OpenAI Codex CLI |
 | `:aider` | `aider` | Aider coding assistant |
 | `:opencode` | `opencode` | OpenCode CLI |
-| `:kilocode` | `kilocode` | Kilocode CLI |
+| `:kilocode` | `kilo` | Kilocode CLI |
+| `:mistral_vibe` | `mistral-vibe` | Mistral Vibe CLI |
+
+### Provider Install Contracts
+
+Provider classes can expose install metadata for downstream apps that build
+their own agent images.
+
+```ruby
+contract = AgentHarness.provider_install_contract(:gemini)
+
+contract[:package_name]
+# => "@google/gemini-cli"
+
+contract[:default_version]
+# => "0.35.3"
+
+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
 
@@ -120,11 +174,157 @@ 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
+metadata instead of hardcoding package names, binary names, or supported
+versions out-of-band.
+
+```ruby
+contract = AgentHarness.provider_installation_contract(:kilocode, version: "7.1.3")
+
+contract
+# {
+#   source: { type: :npm, package: "@kilocode/cli" },
+#   install_command: ["npm", "install", "-g", "--ignore-scripts", "@kilocode/cli@7.1.3"],
+#   binary_name: "kilo",
+#   default_version: "7.1.3",
+#   supported_version_requirement: "= 7.1.3"
+# }
+```
+
+The Kilocode runtime adapter expects the `kilo` binary and executes prompts via
+`kilo run ...`, so the install contract and runtime behavior stay aligned in
+tests.
+
+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
+# => {
+#      source: :npm,
+#      package_name: "opencode-ai",
+#      version: "1.3.2",
+#      version_requirement: [">= 1.3.2", "< 1.4.0"],
+#      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
 
 ```ruby
@@ -138,6 +338,19 @@ class MyProvider < AgentHarness::Providers::Base
       "my-cli"
     end
 
+    def install_contract(version: "1.2.3")
+      {
+        provider: provider_name,
+        source_type: :npm,
+        package_name: "@acme/my-cli",
+        supported_version_requirement: Gem::Requirement.new("~> 1.2"),
+        default_version: "1.2.3",
+        resolved_version: version,
+        binary_name: binary_name,
+        install_command: ["npm", "install", "-g", "@acme/my-cli@#{version}"]
+      }
+    end
+
     def available?
       system("which my-cli > /dev/null 2>&1")
     end

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?