agent-harness 0.2.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 239859e53d6ded09a6a30e02a5ebf4ac5092482d794f7ce494df2c1d711d82fe
+  data.tar.gz: 54db13eb5a096f208c65baa77072ceea9ca5305d71dd01afafc1d4d590d8c6c6
+SHA512:
+  metadata.gz: e50d3e157e97b178747fe89c9cadf8f9993ce317c639161283ec7e16d2dfe2057f486bb8745459feb980745fba90b38a5e96259b63929d7acfdc3da527d7f2a6
+  data.tar.gz: 125252e571a43caa8c0bca133fa1564de465637069af8981792942ad2fc1deb9ce6367083dde39e18fba756bf7545dcad9fb911f2664812dd7db24dbc5b1b20e

data/.markdownlint.yml

@@ -0,0 +1,6 @@
+# Temporary markdownlint configuration to unblock CI and commits.
+# We disable or relax rules that generate large volumes of legacy violations.
+# Follow-up work can selectively re-enable rules and fix content incrementally.
+
+MD013: false # Line length disabled
+MD024: false # Allow duplicate headings (handled semantically by higher-level sections)

data/.markdownlintignore

@@ -0,0 +1,8 @@
+# Ignore auto-generated changelog from lint rules except MD013 (line length disabled separately)
+CHANGELOG.md
+
+# Ignore temporary test files (matches .gitignore)
+tmp/
+
+# devcontainer paths
+vendor/bundle

data/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.2.1"
+}

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.simplecov

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Central SimpleCov configuration.
+# Run with: COVERAGE=1 bundle exec rspec
+
+require "simplecov"
+
+SimpleCov.start do
+  enable_coverage :branch
+
+  track_files "lib/**/*.rb"
+
+  add_filter "lib/agent_harness/version.rb"
+  add_filter "/spec/"
+  add_filter "/pkg/"
+  add_filter "/tmp/"
+
+  add_group "Core", "lib/agent_harness"
+  add_group "Providers", "lib/agent_harness/providers"
+  add_group "Orchestration", "lib/agent_harness/orchestration"
+  add_group "Configuration", "lib/agent_harness/configuration"
+
+  # Match AIDP coverage thresholds
+  minimum_coverage line: 82, branch: 64
+  minimum_coverage_by_file 58
+end

data/.tool-versions

@@ -0,0 +1 @@
+ruby 3.4.8

data/CHANGELOG.md

@@ -0,0 +1,27 @@
+## [Unreleased]
+
+## [0.2.1](https://github.com/viamin/agent-harness/compare/agent-harness/v0.2.0...agent-harness/v0.2.1) (2026-01-26)
+
+
+### Bug Fixes
+
+* add workflow to update release-please lockfile automatically ([0c01f92](https://github.com/viamin/agent-harness/commit/0c01f92b26eb7f1aa12c5a71776b889756240f1f))
+* remove extra-files configuration from release-please config ([3fa12df](https://github.com/viamin/agent-harness/commit/3fa12df710b6b6e6e0ec8f1f8da2de86bc3e8503))
+* update release-please config to include Gemfile.lock as extra file ([be91fff](https://github.com/viamin/agent-harness/commit/be91fff227cc56c0fd9850ac54a2bec09755f8d6))
+
+## [0.2.0](https://github.com/viamin/agent-harness/compare/agent-harness-v0.1.0...agent-harness/v0.2.0) (2026-01-26)
+
+
+### Features
+
+* initial extraction of agent-harness code from aidp ([a87e4ec](https://github.com/viamin/agent-harness/commit/a87e4ecfd50415bb2f4dacb5946cdd84160617bf))
+* initial extraction of agent-harness code from aidp ([8563466](https://github.com/viamin/agent-harness/commit/856346661e06962d5b2c05710a4928f484526931))
+
+
+### Improvements
+
+* streamline command execution and error handling in various modules ([7f0e50c](https://github.com/viamin/agent-harness/commit/7f0e50c9dc00e8b2a81af8738f46fb894b629a2f))
+
+## [0.1.0] - 2026-01-24
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"agent-harness" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["bart@sonic.net"](mailto:"bart@sonic.net").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Bart Agapinan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,274 @@
+# AgentHarness
+
+A unified Ruby interface for CLI-based AI coding agents like Claude Code, Cursor, Gemini CLI, GitHub Copilot, and more.
+
+## 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
+- **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
+- **Error Taxonomy**: Standardized error classification for consistent error handling
+- **Dynamic Registration**: Add custom providers at runtime
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "agent-harness"
+```
+
+Or install directly:
+
+```bash
+gem install agent-harness
+```
+
+## Quick Start
+
+```ruby
+require "agent_harness"
+
+# Send a message using the default provider
+response = AgentHarness.send_message("Write a hello world function in Ruby")
+puts response.output
+
+# Use a specific provider
+response = AgentHarness.send_message("Explain this code", provider: :cursor)
+```
+
+## Configuration
+
+### Ruby DSL
+
+```ruby
+AgentHarness.configure do |config|
+  # Logging
+  config.logger = Logger.new(STDOUT)
+  config.log_level = :info
+
+  # Default provider
+  config.default_provider = :claude
+  config.fallback_providers = [:cursor, :gemini]
+
+  # Timeouts
+  config.default_timeout = 300
+
+  # Orchestration
+  config.orchestration do |orch|
+    orch.enabled = true
+    orch.auto_switch_on_error = true
+    orch.auto_switch_on_rate_limit = true
+
+    orch.circuit_breaker do |cb|
+      cb.enabled = true
+      cb.failure_threshold = 5
+      cb.timeout = 300
+    end
+
+    orch.retry do |r|
+      r.enabled = true
+      r.max_attempts = 3
+      r.base_delay = 1.0
+    end
+  end
+
+  # Provider-specific configuration
+  config.provider(:claude) do |p|
+    p.enabled = true
+    p.timeout = 600
+    p.model = "claude-sonnet-4-20250514"
+  end
+
+  # Callbacks
+  config.on_tokens_used do |event|
+    puts "Used #{event.total_tokens} tokens on #{event.provider}"
+  end
+
+  config.on_provider_switch do |event|
+    puts "Switched from #{event[:from]} to #{event[:to]}: #{event[:reason]}"
+  end
+end
+```
+
+## Providers
+
+### Built-in Providers
+
+| Provider | CLI Binary | Description |
+| -------- | ---------- | ----------- |
+| `:claude` | `claude` | Anthropic Claude Code CLI |
+| `:cursor` | `cursor-agent` | Cursor AI editor CLI |
+| `:gemini` | `gemini` | Google Gemini CLI |
+| `:github_copilot` | `copilot` | GitHub Copilot CLI |
+| `:codex` | `codex` | OpenAI Codex CLI |
+| `:aider` | `aider` | Aider coding assistant |
+| `:opencode` | `opencode` | OpenCode CLI |
+| `:kilocode` | `kilocode` | Kilocode CLI |
+
+### Direct Provider Access
+
+```ruby
+# Get a provider instance
+provider = AgentHarness.provider(:claude)
+response = provider.send_message(prompt: "Hello!")
+
+# Check provider availability
+if AgentHarness::Providers::Registry.instance.get(:claude).available?
+  puts "Claude CLI is installed"
+end
+
+# List all registered providers
+AgentHarness::Providers::Registry.instance.all
+# => [:claude, :cursor, :gemini, :github_copilot, :codex, :opencode, :kilocode, :aider]
+```
+
+### Custom Providers
+
+```ruby
+class MyProvider < AgentHarness::Providers::Base
+  class << self
+    def provider_name
+      :my_provider
+    end
+
+    def binary_name
+      "my-cli"
+    end
+
+    def available?
+      system("which my-cli > /dev/null 2>&1")
+    end
+  end
+
+  protected
+
+  def build_command(prompt, options)
+    [self.class.binary_name, "--prompt", prompt]
+  end
+
+  def parse_response(result, duration:)
+    AgentHarness::Response.new(
+      output: result.stdout,
+      exit_code: result.exit_code,
+      provider: self.class.provider_name,
+      duration: duration
+    )
+  end
+end
+
+# Register the custom provider
+AgentHarness::Providers::Registry.instance.register(:my_provider, MyProvider)
+```
+
+## Orchestration
+
+### Circuit Breaker
+
+Prevents cascading failures by stopping requests to unhealthy providers:
+
+```ruby
+# After 5 consecutive failures, the circuit opens for 5 minutes
+config.orchestration.circuit_breaker.failure_threshold = 5
+config.orchestration.circuit_breaker.timeout = 300
+```
+
+### Rate Limiting
+
+Track and respect provider rate limits:
+
+```ruby
+manager = AgentHarness.conductor.provider_manager
+
+# Mark a provider as rate limited
+manager.mark_rate_limited(:claude, reset_at: Time.now + 3600)
+
+# Check rate limit status
+manager.rate_limited?(:claude)
+```
+
+### Health Monitoring
+
+Monitor provider health and automatically switch on failures:
+
+```ruby
+manager = AgentHarness.conductor.provider_manager
+
+# Record success/failure
+manager.record_success(:claude)
+manager.record_failure(:claude)
+
+# Check health
+manager.healthy?(:claude)
+
+# Get available providers
+manager.available_providers
+```
+
+### Token Tracking
+
+```ruby
+# Track tokens across requests
+AgentHarness.token_tracker.on_tokens_used do |event|
+  puts "Provider: #{event.provider}"
+  puts "Input tokens: #{event.input_tokens}"
+  puts "Output tokens: #{event.output_tokens}"
+  puts "Total: #{event.total_tokens}"
+end
+
+# Get usage summary
+AgentHarness.token_tracker.summary
+```
+
+## Error Handling
+
+```ruby
+begin
+  response = AgentHarness.send_message("Hello")
+rescue AgentHarness::TimeoutError => e
+  puts "Request timed out"
+rescue AgentHarness::RateLimitError => e
+  puts "Rate limited, retry after: #{e.reset_time}"
+rescue AgentHarness::NoProvidersAvailableError => e
+  puts "All providers unavailable: #{e.attempted_providers}"
+rescue AgentHarness::Error => e
+  puts "Provider error: #{e.message}"
+end
+```
+
+### Error Taxonomy
+
+Classify errors for consistent handling:
+
+```ruby
+category = AgentHarness::ErrorTaxonomy.classify_message("rate limit exceeded")
+# => :rate_limited
+
+AgentHarness::ErrorTaxonomy.retryable?(category)
+# => false (rate limits should switch provider, not retry)
+
+AgentHarness::ErrorTaxonomy.action_for(category)
+# => :switch_provider
+```
+
+## Development
+
+```bash
+# Install dependencies
+bin/setup
+
+# Run tests
+bundle exec rake spec
+
+# Run linter
+bundle exec standardrb
+
+# Interactive console
+bin/console
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "fileutils"
+
+# Shared constants
+COVERAGE_DIR = File.expand_path("coverage", __dir__)
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]
+
+# Coverage tasks
+namespace :coverage do
+  desc "Run RSpec with coverage (COVERAGE=1)"
+  task :run do
+    ENV["COVERAGE"] = "1"
+    Rake::Task["spec"].reenable
+    Rake::Task["spec"].invoke
+    puts "\nCoverage report: #{File.join(COVERAGE_DIR, "index.html")}" if File.exist?(File.join(COVERAGE_DIR,
+      "index.html"))
+  end
+
+  desc "Clean coverage artifacts"
+  task :clean do
+    if Dir.exist?(COVERAGE_DIR)
+      rm_r COVERAGE_DIR
+      puts "Removed #{COVERAGE_DIR}"
+    else
+      puts "No coverage directory to remove"
+    end
+  end
+
+  desc "Clean then run coverage"
+  task all: %i[clean run]
+
+  desc "Write coverage summary.json & badge.svg (requires prior coverage:run)"
+  task :summary do
+    require "json"
+    resultset = File.join(COVERAGE_DIR, ".resultset.json")
+    unless File.exist?(resultset)
+      puts "No coverage data found. Run 'rake coverage:run' first."
+      next
+    end
+    data = JSON.parse(File.read(resultset))
+    coverage_hash = data["RSpec"]["coverage"] if data["RSpec"]
+    unless coverage_hash
+      puts "Unexpected resultset structure, cannot find rspec.coverage"
+      next
+    end
+    covered = 0
+    total = 0
+    coverage_hash.each_value do |file_cov|
+      lines = file_cov["lines"]
+      lines.each do |val|
+        next if val.nil?
+
+        total += 1
+        covered += 1 if val > 0
+      end
+    end
+    pct = total.positive? ? (covered.to_f / total * 100.0) : 0.0
+    summary_file = File.join(COVERAGE_DIR, "summary.json")
+    File.write(summary_file, JSON.pretty_generate({timestamp: Time.now.utc.iso8601, line_coverage: pct.round(2)}))
+    # Badge
+    color = case pct
+    when 90..100 then "#4c1"
+    when 80...90 then "#97CA00"
+    when 70...80 then "#dfb317"
+    when 60...70 then "#fe7d37"
+    else "#e05d44"
+    end
+    badge = <<~SVG
+      <svg xmlns="http://www.w3.org/2000/svg" width="150" height="20" role="img" aria-label="coverage: #{pct.round(2)}%">
+        <linearGradient id="s" x2="0" y2="100%"><stop offset="0" stop-color="#bbb" stop-opacity=".1"/><stop offset="1" stop-opacity=".1"/></linearGradient>
+        <rect rx="3" width="150" height="20" fill="#555"/>
+        <rect rx="3" x="70" width="80" height="20" fill="#{color}"/>
+        <path fill="#{color}" d="M70 0h4v20h-4z"/>
+        <rect rx="3" width="150" height="20" fill="url(#s)"/>
+        <g fill="#fff" text-anchor="middle" font-family="DejaVu Sans,Verdana,Geneva,sans-serif" font-size="11">
+          <text x="35" y="14">coverage</text>
+          <text x="110" y="14">#{format("%.2f", pct)}%</text>
+        </g>
+      </svg>
+    SVG
+    # Write standard coverage/badge.svg and duplicate to badges/coverage.svg for README stability
+    File.write(File.join(COVERAGE_DIR, "badge.svg"), badge)
+    badges_dir = File.join("badges")
+    FileUtils.mkdir_p(badges_dir)
+    File.write(File.join(badges_dir, "coverage.svg"), badge)
+    puts "Coverage: #{pct.round(2)}% (summary.json, coverage/badge.svg & badges/coverage.svg written)"
+  end
+end
+
+# Pre-commit preparation task
+desc "Run standard:fix and coverage:run (pre-commit helper)"
+task prep: ["standard:fix", "coverage:run"]
+
+desc "Alias for prep"
+task pc: :prep

data/bin/console

@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "agent/harness"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/agent_harness/command_executor.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+require "shellwords"
+
+module AgentHarness
+  # Executes shell commands with timeout support
+  #
+  # Provides a clean interface for running CLI commands with proper
+  # error handling, timeout support, and result capture.
+  #
+  # @example Basic usage
+  #   executor = AgentHarness::CommandExecutor.new
+  #   result = executor.execute(["claude", "--print", "--prompt", "Hello"])
+  #   puts result.stdout
+  #
+  # @example With timeout
+  #   result = executor.execute("claude --print", timeout: 300)
+  class CommandExecutor
+    # Result of a command execution
+    Result = Struct.new(:stdout, :stderr, :exit_code, :duration, keyword_init: true) do
+      def success?
+        exit_code == 0
+      end
+
+      def failed?
+        !success?
+      end
+    end
+
+    attr_reader :logger
+
+    def initialize(logger: nil)
+      @logger = logger
+    end
+
+    # Execute a command with optional timeout
+    #
+    # @param command [Array<String>, String] command to execute
+    # @param timeout [Integer, nil] timeout in seconds
+    # @param env [Hash] environment variables
+    # @param stdin_data [String, nil] data to send to stdin
+    # @return [Result] execution result
+    # @raise [TimeoutError] if the command times out
+    def execute(command, timeout: nil, env: {}, stdin_data: nil)
+      cmd_array = normalize_command(command)
+      cmd_string = cmd_array.shelljoin
+
+      log_debug("Executing command", command: cmd_string, timeout: timeout)
+
+      start_time = Time.now
+
+      stdout, stderr, status = if timeout
+        execute_with_timeout(cmd_array, timeout: timeout, env: env, stdin_data: stdin_data)
+      else
+        execute_without_timeout(cmd_array, env: env, stdin_data: stdin_data)
+      end
+
+      duration = Time.now - start_time
+
+      Result.new(
+        stdout: stdout,
+        stderr: stderr,
+        exit_code: status.exitstatus,
+        duration: duration
+      )
+    end
+
+    # Check if a binary exists in PATH
+    #
+    # @param binary [String] binary name
+    # @return [String, nil] full path or nil
+    def which(binary)
+      ENV["PATH"].split(File::PATH_SEPARATOR).each do |path|
+        full_path = File.join(path, binary)
+        return full_path if File.executable?(full_path)
+      end
+      nil
+    end
+
+    # Check if a binary is available
+    #
+    # @param binary [String] binary name
+    # @return [Boolean] true if available
+    def available?(binary)
+      !which(binary).nil?
+    end
+
+    private
+
+    def normalize_command(command)
+      case command
+      when Array
+        command.map(&:to_s)
+      when String
+        Shellwords.split(command)
+      else
+        raise ArgumentError, "Command must be Array or String"
+      end
+    end
+
+    def execute_with_timeout(cmd_array, timeout:, env:, stdin_data:)
+      stdout = ""
+      stderr = ""
+      status = nil
+
+      Timeout.timeout(timeout) do
+        Open3.popen3(env, *cmd_array) do |stdin, stdout_io, stderr_io, wait_thr|
+          if stdin_data
+            stdin.write(stdin_data)
+          end
+          stdin.close
+
+          # Read output streams
+          stdout = stdout_io.read
+          stderr = stderr_io.read
+          status = wait_thr.value
+        end
+      end
+
+      [stdout, stderr, status]
+    rescue Timeout::Error
+      raise TimeoutError, "Command timed out after #{timeout} seconds: #{cmd_array.first}"
+    end
+
+    def execute_without_timeout(cmd_array, env:, stdin_data:)
+      Open3.popen3(env, *cmd_array) do |stdin, stdout_io, stderr_io, wait_thr|
+        if stdin_data
+          stdin.write(stdin_data)
+        end
+        stdin.close
+
+        stdout = stdout_io.read
+        stderr = stderr_io.read
+        status = wait_thr.value
+
+        [stdout, stderr, status]
+      end
+    end
+
+    def log_debug(message, **context)
+      @logger&.debug("[AgentHarness::CommandExecutor] #{message}: #{context.inspect}")
+    end
+  end
+end