agent-harness 0.5.7 → 0.5.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2335caa6b19fc12579028ec7c9796c89e588629c7e076b957cac4c6b563d9fdb
-  data.tar.gz: f7bbe39c811548d1f92262ece7d696d9e8486a93c3d494c7cf397c294f41901e
+  metadata.gz: f476f6224ed25cc79c7bc9c8fb239c1df9f787cd59ff279b8c509b7d515d2727
+  data.tar.gz: c0faee9c6d5c139db019707b9174d2d25a4a2fc4a85684ce55eb7baede9fd3be
 SHA512:
-  metadata.gz: e46f340daf52837fa0ae966b5bb2ce1865338b5b9d20d5901b380696e9fac91f35471ec1ef1512f08cc3305346185dfbfd20c2e4a05c2f7ac7d1b466e9dbc5f5
-  data.tar.gz: f6e5c23023174cabf7609b5bf61bc8d07e0a527fa6cc2b219eb19265c1f917897cd846360513c9819a33b970e4180443f0a98a9bc02746bf5c57bafc5ba16b1c
+  metadata.gz: 113c0d8afbf5e77c6abcb1f78f0793646b72137e48a9776bfd951ee98c5412d3606628ea19ce4b105a6d8c05d1143a12a5607e1bad82462c629f6bdf3907985b
+  data.tar.gz: 4cc2f012c75314a2d096147e4bae9afbed565181878a907339410f7cfdb3ea0cff03e96704a6d3d93cd4f3825eb9f21a97d5351b852d72ec4e09b21a3359df68

data/.release-please-manifest.json

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

data/AUDIT_DISPOSITION.md

@@ -0,0 +1,111 @@
+# PR Review Audit Disposition (Issue #91)
+
+Audit of PRs merged before review completion in `viamin/agent-harness`.
+
+## P1 PRs
+
+### PR #55 — Per-request provider runtime overrides
+
+| Finding | Disposition |
+| ------- | ----------- |
+| env stringifies only keys, not values | Fixed in PR #55 itself |
+| Token tracking uses config model instead of runtime model | Fixed in PR #55 itself |
+| nil env/metadata raises NoMethodError | Fixed in PR #55 itself |
+| flags values not validated as Strings | Fixed in PR #55 itself |
+| Adapter Hash-to-ProviderRuntime docs misleading | Fixed in PR #55 itself |
+| `Array(flags)` freezes caller's array | Fixed in PR #55 itself |
+| freezes caller-provided metadata Hash | Fixed in PR #55 itself |
+| env type validation missing | Fixed in PR #55 itself |
+| `.from_hash` no input type check | Fixed in PR #55 itself |
+| flags accepts single String silently | Fixed in PR #55 itself |
+| Cursor never normalizes/uses provider_runtime | Fixed in PR #55 itself |
+| Cursor reimplements build_env instead of calling super | Fixed in PR #55 itself |
+| runtime.model CLI vs telemetry mismatch | Fixed in PR #55 itself |
+| Missing precedence spec | Fixed in PR #55 itself |
+| `.wrap` kwargs bug on Ruby >= 3.2 | Fixed in PR #55 itself |
+| runtime.model precedence unclear | Fixed in PR #55 itself |
+| **base_url/model/api_provider not type-validated** | **Fixed forward in this PR** |
+| **`.from_hash` treats `false` same as missing** | **Fixed forward in this PR** (hash_value helper) |
+| Cursor not mentioned in PR description | Accepted (docs-only, no code impact) |
+
+### PR #81 — Kilocode CLI installation contract
+
+| Finding | Disposition |
+| ------- | ----------- |
+| `installation_contract` can raise NoMethodError for non-Adapter providers | Fixed in PR #81 itself |
+| `provider_installation_contract` doesn't forward `version:` | Fixed in PR #81 itself |
+| Default `installation_contract` doesn't accept `**options` | Fixed in PR #81 itself |
+| Registry forwards `**options` unconditionally | Fixed in PR #81 itself |
+| **`install_command` doesn't handle `version: nil`** | Accepted (produces clear error message via Gem::Version coercion) |
+| **`validate_install_version!` gives generic error for bad input** | **Fixed forward in this PR** |
+
+### PR #57 — Provider configuration capabilities
+
+| Finding | Disposition |
+| ------- | ----------- |
+| All 19 findings (schema field removal, auth_modes derivation, model hints, accepts_arbitrary alignment) | All fixed in PR #57 itself across 5 review rounds |
+
+### PR #42 — Gemini and Codex health/auth checks
+
+| Finding | Disposition |
+| ------- | ----------- |
+| Temp dir from Dir.mktmpdir never cleaned up | Fixed in PR #42 itself |
+| Config-file API key not validated for sk- prefix | Fixed in PR #42 itself |
+| Error message hardcodes ~/.codex/config.json | Fixed in PR #42 itself |
+| default_flags assumed to be Array, no guard | Fixed in PR #42 itself |
+| Error message only mentions GEMINI_API_KEY | Fixed in PR #42 itself |
+| validate_config doesn't check model/flags types | Fixed in PR #42 itself |
+| JSON parse error leaks credential file contents | Fixed in PR #42 itself |
+| Blank GEMINI_API_KEY doesn't fall back | Fixed in PR #42 itself |
+| validate_config validates default_flags but build_command never uses them | Fixed in PR #42 itself |
+| build_command raises if default_flags is non-Array | Fixed in PR #42 itself |
+| auth_status assumes parsed JSON is Hash | Fixed in PR #42 itself |
+| **auth_status returns inconsistent hash shape (missing auth_method)** | **Fixed forward in this PR** (both Codex and Gemini) |
+| **Numeric status-code regexes can match unrelated numbers** | **Fixed forward in this PR** (added `\b` word boundaries) |
+
+## P2 PRs
+
+### PR #16 — DockerCommandExecutor
+
+| Finding | Disposition |
+| ------- | ----------- |
+| Duplicated `normalize_command` method | Already resolved (inherits from protected parent) |
+| `which` missing timeout | Already resolved (timeout: 5 added) |
+| **container_id not validated for whitespace-only** | **Fixed forward in this PR** |
+| Test stubs don't assert command arguments | Accepted (test quality, not a runtime defect) |
+
+### PR #83 — OpenCode CLI installation contract
+
+| Finding | Disposition |
+| ------- | ----------- |
+| No unresolved review comments | No action needed |
+
+### PR #80 — Gemini CLI installation contract
+
+| Finding | Disposition |
+| ------- | ----------- |
+| `install_contract` signature mismatch between base adapter and callers | Already resolved in current adapter.rb |
+| No guard for providers without `install_contract` | Already resolved in registry.rb |
+| **Malformed version strings not handled gracefully** | Already resolved (Gemini rescues ArgumentError from Gem::Version) |
+| Missing test coverage for edge cases | Accepted (test quality, not a runtime defect) |
+
+### PR #1 — Initial extraction
+
+| Finding | Disposition |
+| ------- | ----------- |
+| `timecop` gem not declared in Gemfile | Already resolved (timecop removed from codebase) |
+| Missing YamlLoader/EnvLoader files | Already resolved (references removed) |
+| README binary name for Cursor incorrect | Already resolved (README says cursor-agent, matches code) |
+| README binary name for GitHub Copilot incorrect | Already resolved (README updated) |
+| bin/ excluded from gemspec | Accepted (intentional for gem packaging) |
+
+## Summary of fixes in this PR
+
+1. **ProviderRuntime**: Added type validation for `model`, `base_url`, `api_provider` (must be String or nil)
+2. **ProviderRuntime**: Replaced `||`-based hash key lookup in `.from_hash` with `hash_value` helper that distinguishes nil from missing keys
+3. **Codex auth_status**: Added consistent `auth_method` key to all return paths
+4. **Gemini auth_status**: Added consistent `auth_method` key to all return paths
+5. **Codex error_patterns**: Added `\b` word boundaries to `/401/` regex
+6. **Gemini error_patterns**: Added `\b` word boundaries to `/429/` and `/503/` regexes
+7. **Kilocode**: `validate_install_version!` now rescues malformed version strings with a provider-specific error message
+8. **DockerCommandExecutor**: Validates whitespace-only `container_id` values

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## [Unreleased]
 
+## [0.5.9](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.8...agent-harness/v0.5.9) (2026-04-12)
+
+
+### Bug Fixes
+
+* 91: audit and fix-forward defects from PRs merged before review completion ([ec0af12](https://github.com/viamin/agent-harness/commit/ec0af12728f6524b651ebc9b552c477059a2adac))
+* **providers:** close path traversal bypass in env-var-prefixed preparation paths ([493bf55](https://github.com/viamin/agent-harness/commit/493bf55be088a8bde39d143791f3f9b0c90d9c0c))
+* **providers:** harden preparation path validation against env value traversal and command substitution ([ed4b92b](https://github.com/viamin/agent-harness/commit/ed4b92b8760ec4dfa1f50d69b0736563140905b4))
+* **providers:** harden preparation path validation against injection and traversal ([9cb0faf](https://github.com/viamin/agent-harness/commit/9cb0fafbf63c908c7ef7b465bf541ceb5dbf58bb))
+* **providers:** preserve docker idle timeouts ([adde6b4](https://github.com/viamin/agent-harness/commit/adde6b4491023c8baf37249147770cddeff1b0ee))
+
+## [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?