agent-harness 0.39.0 → 0.40.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b6b9b84a3074d82a44dd35a6b377628c64cfa01958ca5c41ec910b694375fcf
-  data.tar.gz: 8069427d9a79624deba026984490a5f25cf97df7364c6d78b44c2a43aef773c6
+  metadata.gz: ee00d0e61838facc87483e6bdcac764ed26dc5bb227a15075b4e8f0daa8983d4
+  data.tar.gz: 6034f1733639711ad2b7df6bf9c26da839d45c26d1ddb6b0b4e5ba413854fc8a
 SHA512:
-  metadata.gz: cad34514f544dcf13a470afbb7cbdde82269246ee16d97319e3e6f33afd2e663b0625fd2f088bc4c68ef491676ac3c5cfc80e6bc3ba5a030fbda1abbe9a04cf7
-  data.tar.gz: 48fd85599fca1ae94fe13e433d4a69d1ab5bd8ce4c9c8feab6388c79c2d48c5314467cba8c4fcb277662c1aea20f53206b35fef6cad0a82ef82618249a80a883
+  metadata.gz: 130a2897522e8b1aa73b2a9cf6094bd24b3b529696445e84356a78faa02540e0c4c2677602e306fca60e1f1a3040e48c04b3ff0a9ca28f144a24de6fc3fa5887
+  data.tar.gz: 647ab39ee27728d28a3441ccbbd84edd3521e7e434a120ac236e411849b22aa431ae7fc6dbe499ec8c525aee6159c9fdba42a5ee8ff7ec329281dd7ea3a4ad33

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.39.0"
+  ".": "0.40.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,13 @@
 * add runner model compatibility contract (`AgentHarness.model_compatibility`) with structured `ModelCompatibility::Result` outcomes. Codex exposes static facts for CLI-gated models (e.g. `gpt-5.5` requires Codex CLI `>= 0.116.0`), a baseline supported-model list, supported auth modes, and a `DEFAULT_COMPATIBLE_MODEL_ID` fallback so downstream orchestrators can validate tier/model assignments before scheduling agent runs ([#259](https://github.com/viamin/agent-harness/issues/259)).
 * **auth:** add provider-owned PKCE code-exchange API for Claude OAuth (`AgentHarness::Authentication.exchange_code`). Takes an authorization code plus PKCE verifier (and `redirect_uri`/`client_id`), posts an `authorization_code` grant to the Claude token endpoint, and persists the resulting access/refresh tokens in the native `claudeAiOauth` shape. Adds `exchange_code_supported?` and a `code_exchange` key to `auth_capabilities` ([#266](https://github.com/viamin/agent-harness/issues/266)).
 
+## [0.40.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.39.0...agent-harness/v0.40.0) (2026-09-25)
+
+
+### Features
+
+* Provide Native Embedding Support (RDR-072) ([#439](https://github.com/viamin/agent-harness/issues/439)) ([551378d](https://github.com/viamin/agent-harness/commit/551378d11627a5227059032f0b7418dc166f54e9))
+
 ## [0.39.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.38.0...agent-harness/v0.39.0) (2026-09-25)
 
 

data/README.md

@@ -39,6 +39,71 @@ puts response.output
 response = AgentHarness.send_message("Explain this code", provider: :cursor)
 ```
 
+## Native Embeddings
+
+`AgentHarness.embed` sends a whole input batch through RubyLLM and returns one
+vector per input, in the same order. Credentials, endpoint, headers, timeout,
+and retry limits are request-local; they do not change `RubyLLM.config` or the
+CLI/subscription provider configuration.
+
+```ruby
+result = AgentHarness.embed(
+  inputs: ["first document", "second document"],
+  model: "text-embedding-3-small",
+  dimensions: 512,
+  endpoint: "https://api.openai.com/v1", # optional OpenAI-compatible base URL
+  credentials: {api_key: ENV.fetch("EMBEDDING_API_KEY")},
+  headers: {"X-Tenant-ID" => tenant.external_id},
+  timeout: 30,
+  max_attempts: 3,
+  cancellation: -> { request_cancelled? }
+)
+
+result.vectors # one vector for each input
+result.usage   # { input_tokens: 42 }
+```
+
+`credentials` may also be the API key string. Extra headers cannot replace the
+`Authorization` header; change credentials explicitly instead. `max_attempts`
+includes the initial request. Agent Harness performs the only retry loop: 429,
+timeout/connection, and transient 5xx failures are retried up to that bound,
+while 401 and 403 responses fail immediately. The harness honors `Retry-After`
+within its bounded retry policy. A cancellation callable is checked immediately
+before every physical HTTP attempt.
+
+Usage is the provider-reported total for the complete batch. When the provider
+omits usage, `result.usage[:input_tokens]` remains `nil`. The harness does not
+estimate usage or allocate a batch total across vectors, so
+`result.per_vector_usage` is always `nil`.
+
+Authentication failures raise `AgentHarness::AuthenticationError`, exhausted
+rate limits raise `AgentHarness::RateLimitError`, timeouts raise
+`AgentHarness::TimeoutError`, transient provider failures raise
+`AgentHarness::ProviderError`, cancellations raise
+`AgentHarness::CancelledError`, and incomplete or invalid vector batches raise
+`AgentHarness::MalformedEmbeddingError`. Empty input returns an empty result
+without contacting the provider.
+
+### Migrating from Paid transport patches
+
+This operation replaces downstream host/container embedding transport
+extensions for OpenAI-compatible direct and proxy endpoints. After adopting an
+agent-harness release containing this capability:
+
+1. Run the downstream embedding contract suite against both the direct provider
+   and proxy endpoint, including tenant-specific credentials and headers.
+2. Verify the released gem artifact includes `AgentHarness.embed` and record the
+   passing artifact version or digest. Issue closure or a Git tag alone is not
+   release evidence.
+3. Switch only the embedding call site to `AgentHarness.embed`; leave unrelated
+   chat, schema, CLI, and subscription paths unchanged.
+4. Remove the downstream embedding request/parser/retry patch so Agent Harness
+   owns the single bounded retry loop. Keep durable workflow recovery and
+   accounting in the downstream application.
+
+The runtime dependency is Ruby 3.2 or newer and RubyLLM 2.x. No Rails database
+or RubyLLM persistence tables are required for this plain-Ruby operation.
+
 ## Configuration
 
 ### Ruby DSL

data/lib/agent_harness/embedding_adapter.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/net_http"
+require "json"
+
+module AgentHarness
+  # Builds a request-local Faraday adapter for headers and cancellation.
+  module EmbeddingAdapter
+    module_function
+
+    def build(headers:, cancellation: nil)
+      Class.new(Faraday::Adapter::NetHttp) do
+        define_method(:call) do |env|
+          raise CancelledError, "Embedding request cancelled" if cancellation&.call
+
+          env.request_headers.update(headers)
+          super(env).on_complete { |response| EmbeddingAdapter.order_rows(response) }
+        end
+      end
+    end
+
+    def order_rows(response)
+      payload = JSON.parse(response.body)
+      rows = payload["data"]
+      return unless rows.is_a?(Array)
+
+      indices = rows.map { |row| row["index"] if row.is_a?(Hash) }
+      unless indices.all?(Integer) && indices.sort == (0...rows.length).to_a
+        raise MalformedEmbeddingError, "Provider returned invalid embedding indices"
+      end
+
+      payload["data"] = rows.sort_by { |row| row.fetch("index") }
+      response.body = JSON.generate(payload)
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/agent_harness/embedding_result.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  # Normalized result returned by AgentHarness.embed.
+  class EmbeddingResult
+    attr_reader :vectors, :model, :usage, :attempts
+
+    def initialize(vectors:, model:, input_tokens: nil, attempts: [])
+      @vectors = vectors
+      @model = model
+      @usage = {input_tokens: input_tokens}.freeze
+      @attempts = attempts.freeze
+    end
+
+    # Batch usage is never guessed or divided among individual vectors.
+    def per_vector_usage
+      nil
+    end
+  end
+end

data/lib/agent_harness/embeddings.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "securerandom"
+require "time"
+
+module AgentHarness
+  # Provider-neutral embedding execution backed by RubyLLM.
+  class Embeddings
+    DEFAULT_TIMEOUT = 300
+    DEFAULT_MAX_ATTEMPTS = 3
+    RETRY_BASE_DELAY = 0.25
+    RETRY_MAX_DELAY = 2.0
+    CANCELLATION_POLL_INTERVAL = 0.05
+    TRANSIENT_ERRORS = [RateLimitError, TimeoutError].freeze
+
+    def initialize(model:, credentials:, endpoint: nil, headers: {}, timeout: DEFAULT_TIMEOUT,
+      max_attempts: DEFAULT_MAX_ATTEMPTS, cancellation: nil, observer: nil, request_id: nil)
+      @model = model
+      @api_key = credential(credentials, :api_key)
+      @endpoint = endpoint
+      @headers = headers.to_h.transform_keys(&:to_s).freeze
+      @timeout = timeout
+      @max_attempts = max_attempts
+      @cancellation = cancellation
+      @observer = observer
+      @request_id = request_id || SecureRandom.uuid
+      validate!
+    end
+
+    def call(inputs:, dimensions: nil)
+      inputs = Array(inputs)
+      return EmbeddingResult.new(vectors: [], model: @model) if inputs.empty?
+
+      execute(inputs, dimensions)
+    end
+
+    private
+
+    def execute(inputs, dimensions)
+      attempts = []
+
+      1.upto(@max_attempts) do |number|
+        check_cancellation!
+        result = attempt(inputs, dimensions, number, attempts)
+        return result
+      rescue RateLimitError, TimeoutError, ProviderError => e
+        raise unless retryable?(e) && number < @max_attempts
+
+        wait_before_retry(e, number)
+      end
+    end
+
+    def attempt(inputs, dimensions, number, attempts)
+      started_at = Time.now.utc
+      embedding = request_embedding(inputs, dimensions)
+      validate_result!(embedding.vectors, inputs.length)
+      report = success_report(embedding, number, started_at)
+    rescue CancelledError => e
+      record_attempt(attempts, failure_report(e, number, started_at, :cancelled, :cancelled))
+      raise
+    rescue AuthenticationError, AuthorizationError, RateLimitError, TimeoutError, ProviderError => e
+      record_attempt(attempts, failure_report(e, number, started_at, *error_classification(e)))
+      raise
+    rescue NoMethodError, TypeError => e
+      error = MalformedEmbeddingError.new("Malformed embedding response", original_error: e)
+      record_attempt(attempts, failure_report(error, number, started_at, *error_classification(error)))
+      raise error
+    else
+      record_attempt(attempts, report)
+      EmbeddingResult.new(
+        vectors: embedding.vectors, model: embedding.model,
+        input_tokens: embedding.tokens.input, attempts: attempts
+      )
+    end
+
+    def request_embedding(inputs, dimensions)
+      context.embed(
+        inputs,
+        model: @model,
+        provider: :openai,
+        assume_model_exists: true,
+        dimensions: dimensions
+      )
+    rescue RubyLLM::UnauthorizedError => e
+      raise AuthenticationError.new(e.message, provider: :openai, original_error: e)
+    rescue RubyLLM::ForbiddenError => e
+      raise AuthorizationError.new(e.message, provider: :openai, original_error: e)
+    rescue RubyLLM::RateLimitError => e
+      raise RateLimitError.new(e.message, provider: :openai, reset_time: retry_after(e), original_error: e)
+    rescue Faraday::TimeoutError, Timeout::Error => e
+      raise TimeoutError.new(e.message, original_error: e)
+    rescue Faraday::ConnectionFailed => e
+      raise connection_error(e)
+    rescue RubyLLM::ServerError, RubyLLM::ServiceUnavailableError, RubyLLM::OverloadedError => e
+      raise ProviderError.new(e.message, original_error: e)
+    rescue Faraday::ParsingError, NoMethodError, TypeError => e
+      raise MalformedEmbeddingError.new("Malformed embedding response", original_error: e)
+    rescue RubyLLM::Error => e
+      raise ProviderError.new(e.message, original_error: e)
+    end
+
+    def context
+      RubyLLM.context do |config|
+        config.openai_api_key = @api_key
+        config.openai_api_base = @endpoint if @endpoint
+        config.request_timeout = @timeout
+        config.max_retries = 0
+        config.retry_interval_randomness = 0
+        config.faraday_adapter = EmbeddingAdapter.build(headers: @headers, cancellation: @cancellation)
+      end
+    end
+
+    def success_report(embedding, number, started_at)
+      attempt_report(number, started_at).merge(
+        status: :succeeded,
+        model: embedding.model,
+        usage: usage(embedding.tokens.input),
+        provider_reported: !embedding.tokens.input.nil?,
+        error: nil
+      ).freeze
+    end
+
+    def failure_report(error, number, started_at, category, code)
+      attempt_report(number, started_at).merge(
+        status: (category == :cancelled) ? :cancelled : :failed,
+        usage: usage(nil),
+        provider_reported: false,
+        error: {category: category, code: code}.freeze
+      ).freeze
+    end
+
+    def attempt_report(number, started_at)
+      {
+        attempt_id: "attempt_#{SecureRandom.uuid}", request_id: @request_id,
+        number: number, provider: :openai, model: @model,
+        started_at: started_at.iso8601(6), finished_at: Time.now.utc.iso8601(6),
+        cost: nil, provider_request_id: nil
+      }
+    end
+
+    def usage(input_tokens)
+      {input_tokens: input_tokens, output_tokens: nil, total_tokens: input_tokens}.freeze
+    end
+
+    def record_attempt(attempts, report)
+      attempts << report
+      return unless @observer
+
+      @observer.respond_to?(:on_attempt) ? @observer.on_attempt(report) : @observer.call(report)
+    end
+
+    def error_classification(error)
+      return [error.error_category, error.error_code] if error.is_a?(AuthenticationError) || error.is_a?(AuthorizationError)
+      return [:transient, :rate_limited] if error.is_a?(RateLimitError)
+      return [:transient, :timeout] if error.is_a?(TimeoutError)
+      return transient_provider_classification(error) if transient_provider_error?(error)
+      return [:invalid_response, :malformed_response] if error.is_a?(MalformedEmbeddingError)
+
+      [:unknown, :unclassified_provider_error]
+    end
+
+    def transient_provider_classification(error)
+      original = error.original_error
+      return [:transient, :connection_failed] if original.is_a?(Faraday::ConnectionFailed)
+      return [:transient, :service_unavailable] if original.is_a?(RubyLLM::ServiceUnavailableError)
+      return [:transient, :overloaded] if original.is_a?(RubyLLM::OverloadedError)
+
+      [:transient, :server_error]
+    end
+
+    def retryable?(error)
+      TRANSIENT_ERRORS.any? { |klass| error.is_a?(klass) } || transient_provider_error?(error)
+    end
+
+    def transient_provider_error?(error)
+      original = error.original_error
+      original.is_a?(Faraday::ConnectionFailed) || original.is_a?(RubyLLM::ServerError) ||
+        original.is_a?(RubyLLM::ServiceUnavailableError) || original.is_a?(RubyLLM::OverloadedError)
+    end
+
+    def wait_before_retry(error, attempt_number)
+      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + retry_delay(error, attempt_number)
+      loop do
+        check_cancellation!
+        remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        break unless remaining.positive?
+
+        sleep([remaining, CANCELLATION_POLL_INTERVAL].min)
+      end
+    end
+
+    def retry_delay(error, attempt_number)
+      retry_after_delay = error.reset_time - Time.now if error.is_a?(RateLimitError) && error.reset_time
+      return retry_after_delay if retry_after_delay&.positive?
+
+      [RETRY_BASE_DELAY * (2**(attempt_number - 1)), RETRY_MAX_DELAY].min
+    end
+
+    def check_cancellation!
+      raise CancelledError, "Embedding request cancelled" if @cancellation&.call
+    end
+
+    def validate_result!(vectors, expected_count)
+      valid = vectors.is_a?(Array) && vectors.length == expected_count
+      valid &&= vectors.all? { |vector| valid_vector?(vector) }
+      raise MalformedEmbeddingError, "Provider returned an invalid embedding batch" unless valid
+    end
+
+    def valid_vector?(vector)
+      vector.is_a?(Array) && !vector.empty? && vector.all? { |value| value.is_a?(Numeric) && value.finite? }
+    end
+
+    def credential(credentials, key)
+      return credentials if credentials.is_a?(String)
+
+      credentials&.[](key) || credentials&.[](key.to_s)
+    end
+
+    def validate!
+      raise ArgumentError, "model must be a non-empty string" unless @model.is_a?(String) && !@model.empty?
+      raise ArgumentError, "credentials must include api_key" unless @api_key.is_a?(String) && !@api_key.empty?
+      if @headers.keys.any? { |header| header.casecmp?("authorization") }
+        raise ArgumentError, "headers cannot override Authorization; use credentials"
+      end
+      raise ArgumentError, "timeout must be positive" unless @timeout.is_a?(Numeric) && @timeout.positive?
+      unless @max_attempts.is_a?(Integer) && @max_attempts.positive?
+        raise ArgumentError, "max_attempts must be a positive integer"
+      end
+      unless @request_id.is_a?(String) && !@request_id.empty?
+        raise ArgumentError, "request_id must be a non-empty string"
+      end
+      unless @observer.nil? || @observer.respond_to?(:on_attempt) || @observer.respond_to?(:call)
+        raise ArgumentError, "observer must respond to on_attempt or call"
+      end
+    end
+
+    def retry_after(error)
+      value = error.response&.response_headers&.[]("retry-after")
+      return unless value
+
+      seconds = Float(value, exception: false)
+      seconds ? Time.now + seconds : Time.httpdate(value)
+    rescue ArgumentError, TypeError
+      nil
+    end
+
+    def connection_error(error)
+      wrapped = error.wrapped_exception
+      if wrapped.is_a?(Timeout::Error)
+        TimeoutError.new(error.message, original_error: error)
+      else
+        ProviderError.new(error.message, original_error: error)
+      end
+    end
+  end
+end

data/lib/agent_harness/errors.rb

@@ -15,6 +15,9 @@ module AgentHarness
   # Provider-related errors
   class ProviderError < Error; end
 
+  # Raised when an embedding provider response cannot satisfy the batch contract.
+  class MalformedEmbeddingError < ProviderError; end
+
   class ProviderInstallationError < ProviderError
     attr_reader :provider, :error_category
 
@@ -39,6 +42,9 @@ module AgentHarness
 
   class CommandExecutionError < Error; end
 
+  # Raised when a caller cancels a request before a transport attempt.
+  class CancelledError < Error; end
+
   # Rate limiting and circuit breaker errors
   class RateLimitError < Error
     attr_reader :reset_time, :provider, :error_category
@@ -62,10 +68,24 @@ module AgentHarness
 
   # Authentication errors
   class AuthenticationError < Error
-    attr_reader :provider
+    attr_reader :provider, :error_category, :error_code
 
-    def initialize(message = nil, provider: nil, **kwargs)
+    def initialize(message = nil, provider: nil, error_category: :authentication, error_code: :invalid_credential, **kwargs)
+      @provider = provider
+      @error_category = error_category
+      @error_code = error_code
+      super(message, **kwargs)
+    end
+  end
+
+  # Raised when valid credentials do not grant access to the requested resource.
+  class AuthorizationError < Error
+    attr_reader :provider, :error_category, :error_code
+
+    def initialize(message = nil, provider: nil, error_category: :authorization, error_code: :permission_denied, **kwargs)
       @provider = provider
+      @error_category = error_category
+      @error_code = error_code
       super(message, **kwargs)
     end
   end

data/lib/agent_harness/version.rb

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

data/lib/agent_harness.rb

@@ -87,6 +87,12 @@ module AgentHarness
       conductor.send_message(prompt, provider: provider, executor: executor, **options)
     end
 
+    # Generate embeddings for a batch of strings through a request-local RubyLLM context.
+    # @return [EmbeddingResult] vectors in input order and provider-reported batch usage
+    def embed(inputs:, model:, credentials:, dimensions: nil, **options)
+      Embeddings.new(model: model, credentials: credentials, **options).call(inputs: inputs, dimensions: dimensions)
+    end
+
     # Resolve a canonical extension definition by name or inline object.
     #
     # @param reference [Symbol, String, Extensions::Base]
@@ -456,6 +462,9 @@ require_relative "agent_harness/configuration"
 require_relative "agent_harness/command_executor"
 require_relative "agent_harness/docker_command_executor"
 require_relative "agent_harness/response"
+require_relative "agent_harness/embedding_result"
+require_relative "agent_harness/embedding_adapter"
+require_relative "agent_harness/embeddings"
 require_relative "agent_harness/token_tracker"
 require_relative "agent_harness/token_usage_tracker"
 require_relative "agent_harness/error_taxonomy"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.39.0
+  version: 0.40.0
 platform: ruby
 authors:
 - Bart Agapinan
@@ -29,6 +29,26 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: ruby_llm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -71,6 +91,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
 description: |
   AgentHarness provides a unified interface for CLI-based AI coding agents like
   Claude Code, Cursor, Gemini CLI, and others. It offers full orchestration with
@@ -107,6 +141,9 @@ files:
 - lib/agent_harness/conversation.rb
 - lib/agent_harness/dependency_updater.rb
 - lib/agent_harness/docker_command_executor.rb
+- lib/agent_harness/embedding_adapter.rb
+- lib/agent_harness/embedding_result.rb
+- lib/agent_harness/embeddings.rb
 - lib/agent_harness/error_taxonomy.rb
 - lib/agent_harness/errors.rb
 - lib/agent_harness/execution_preparation.rb