agent-harness 0.23.0 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0874add2f55550c3c9f9b723c84a4036a2dd79dd717dd62069062cfbde630820'
-  data.tar.gz: 53c6335c3a47e4e0e18ea3151dad061f9302519013e27591c7541ebf6dfe51db
+  metadata.gz: 1afbed6f9dcafe6c80575c77a128ba73b407f4cd691bd45ce19bfa48b613ccb2
+  data.tar.gz: b158dd410320320093c897795839b20eedea35383784692c0038893dca163123
 SHA512:
-  metadata.gz: a7297580e4a5a34631421730cab4c0fc5712448864bacefe8c8f3c43c7652b5a42cb9f7c2a603f585f308d2a54117dff918804a45a30c3bb302ec223e545eed4
-  data.tar.gz: 36428c8e91bee3395d235cd4ae309f6a43c177acc6991cdf3cd33ed4f0cc433a566849a8b282137466a455da5becdc63820a87a01a36eb8399f857ecbe457ef7
+  metadata.gz: fb7e2eda150529ba550829380171bc432bbe5025de3ad8d7c5f5799354b8a4a1e6209a788ef2fbc9ca90898d24ee4b1769f4f693619d75d90bd47b2021edc12a
+  data.tar.gz: c55f52bf3498750daf7bc4919d1100705e8b5fcb1f8c540852022cd852a28988654cf84771cae0d3bdf08a9f8a7648e7a2514234b5fc06d70e6a54b159ce1ab6

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.23.0"
+  ".": "0.25.0"
 }

data/CHANGELOG.md

@@ -5,6 +5,20 @@
 * 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)).
 
 
+## [0.25.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.24.0...agent-harness/v0.25.0) (2026-06-26)
+
+
+### Features
+
+* **auth:** add refresh-token exchange API for Claude OAuth ([#269](https://github.com/viamin/agent-harness/issues/269)) ([076b1aa](https://github.com/viamin/agent-harness/commit/076b1aa91a3dcb58280d1c550bdc4329ce162a92)), closes [#265](https://github.com/viamin/agent-harness/issues/265)
+
+## [0.24.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.23.0...agent-harness/v0.24.0) (2026-06-26)
+
+
+### Features
+
+* **auth:** parse native Claude claudeAiOauth credentials shape ([#268](https://github.com/viamin/agent-harness/issues/268)) ([178edae](https://github.com/viamin/agent-harness/commit/178edae21e175c4744b75a151acfc6df3b4b3c5d)), closes [#264](https://github.com/viamin/agent-harness/issues/264)
+
 ## [0.23.0](https://github.com/viamin/agent-harness/compare/agent-harness/v0.22.5...agent-harness/v0.23.0) (2026-06-15)
 
 

data/lib/agent_harness/authentication.rb

@@ -2,8 +2,10 @@
 
 require "json"
 require "fileutils"
+require "net/http"
 require "tempfile"
 require "time"
+require "uri"
 
 module AgentHarness
   # Authentication management for CLI agent providers
@@ -49,7 +51,8 @@ module AgentHarness
         {
           auth_type: provider.auth_type,
           auth_url: flow_supported,
-          refresh: flow_supported
+          refresh: flow_supported,
+          exchange: flow_supported
         }
       end
 
@@ -126,6 +129,49 @@ module AgentHarness
         end
       end
 
+      # Check whether refresh-token exchange is supported for a provider.
+      #
+      # @param provider_name [Symbol] the provider name
+      # @return [Boolean] true if exchange_refresh_token can be called
+      # @raise [ProviderNotFoundError] if provider is unknown
+      def exchange_refresh_token_supported?(provider_name)
+        auth_capabilities(provider_name)[:exchange]
+      end
+
+      # Exchange a stored refresh token for a fresh access token (and rotated refresh token).
+      #
+      # Reads the refresh token from the provider's credentials store, posts it to the
+      # OAuth token endpoint, persists the rotated tokens, and returns the credential
+      # in native claudeAiOauth shape.
+      #
+      # Serializes through a file lock so that concurrent callers do not race on a
+      # single-use/rotating refresh token.  If the token server reports that the
+      # refresh token has already been consumed (`refresh_token_reused`), raises
+      # +AuthenticationError+ so the caller can trigger a full re-auth.
+      #
+      # @param provider_name [Symbol] the provider name
+      # @return [Hash] credential in claudeAiOauth shape:
+      #   +{ claudeAiOauth: { accessToken:, refreshToken:, expiresAt: } }+
+      # @raise [UnsupportedAuthFlowError] if provider doesn't support token exchange
+      # @raise [AuthenticationError] if the refresh token is missing, reused, or exchange fails
+      def exchange_refresh_token(provider_name)
+        provider_name = provider_name.to_sym
+        provider = resolve_provider(provider_name)
+
+        unless provider.auth_type == :oauth
+          raise UnsupportedAuthFlowError,
+            "Provider #{provider_name} uses #{provider.auth_type} auth and does not support token exchange"
+        end
+
+        case provider_name
+        when :claude, :anthropic
+          exchange_claude_refresh_token
+        else
+          raise UnsupportedAuthFlowError,
+            "Token exchange is not yet implemented for provider #{provider_name}"
+        end
+      end
+
       private
 
       def claude_oauth_flow_provider?(requested_name, canonical_name)
@@ -163,12 +209,8 @@ module AgentHarness
         credentials = read_claude_credentials
         return {valid: false, expires_at: nil, error: "No credentials found"} unless credentials
 
-        # Check if the credentials file has a token, preferring a non-blank oauth_token over apiKey
-        oauth_token = credentials["oauth_token"]
-        api_key = credentials["apiKey"]
-        token = [oauth_token, api_key].find { |t| t.is_a?(String) && !t.strip.empty? }
+        token, expires_at = extract_claude_token(credentials)
         if token
-          expires_at = parse_expiry(credentials["expiresAt"] || credentials["expires_at"])
           if expires_at && expires_at < Time.now
             {valid: false, expires_at: expires_at, error: "Session expired"}
           else
@@ -224,10 +266,20 @@ module AgentHarness
 
           credentials = read_claude_credentials
           credentials = {} unless credentials.is_a?(Hash)
-          credentials["oauth_token"] = token.strip
-          # Clear any existing expiry metadata so refreshed tokens are not treated as expired
-          credentials.delete("expiresAt")
-          credentials.delete("expires_at")
+
+          if credentials.key?("claudeAiOauth")
+            # Preserve the native claudeAiOauth shape
+            oauth = credentials["claudeAiOauth"]
+            oauth = {} unless oauth.is_a?(Hash)
+            oauth["accessToken"] = token.strip
+            oauth.delete("expiresAt")
+            credentials["claudeAiOauth"] = oauth
+          else
+            credentials["oauth_token"] = token.strip
+            # Clear any existing expiry metadata so refreshed tokens are not treated as expired
+            credentials.delete("expiresAt")
+            credentials.delete("expires_at")
+          end
 
           # Write under a file lock using tempfile + rename to avoid corruption and lost updates on concurrent refreshes
           tmpfile = Tempfile.new(".credentials", dir)
@@ -245,6 +297,135 @@ module AgentHarness
         {success: true}
       end
 
+      # Token endpoint used for Claude OAuth refresh-token exchange.
+      CLAUDE_TOKEN_ENDPOINT = URI("https://claude.ai/oauth/token").freeze
+
+      def exchange_claude_refresh_token
+        credentials_path = claude_credentials_path
+        lock_path = "#{credentials_path}.lock"
+
+        dir = File.dirname(credentials_path)
+        FileUtils.mkdir_p(dir, mode: 0o700)
+
+        File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
+          lock.flock(File::LOCK_EX)
+
+          credentials = read_claude_credentials
+          refresh_token = credentials&.dig("claudeAiOauth", "refreshToken")
+          refresh_token = nil if refresh_token.is_a?(String) && refresh_token.strip.empty?
+
+          unless refresh_token
+            raise AuthenticationError.new(
+              "No refresh token found in Claude credentials",
+              provider: :claude
+            )
+          end
+
+          response_body = post_token_exchange(refresh_token)
+
+          access_token = response_body["access_token"]
+          new_refresh_token = response_body["refresh_token"]
+          expires_in = response_body["expires_in"]
+
+          expires_at = expires_in ? (Time.now + expires_in).iso8601 : nil
+
+          oauth_block = {
+            "accessToken" => access_token,
+            "refreshToken" => new_refresh_token,
+            "expiresAt" => expires_at
+          }
+
+          credentials["claudeAiOauth"] = oauth_block
+          credentials["oauth_token"] = access_token
+          credentials.delete("expiresAt")
+          credentials.delete("expires_at")
+          credentials["expiresAt"] = expires_at
+
+          tmpfile = Tempfile.new(".credentials", dir)
+          begin
+            tmpfile.write(JSON.pretty_generate(credentials))
+            tmpfile.close
+            File.chmod(0o600, tmpfile.path)
+            File.rename(tmpfile.path, credentials_path)
+          rescue
+            tmpfile.close!
+            raise
+          end
+
+          {claudeAiOauth: oauth_block.transform_keys(&:to_sym)}
+        end
+      end
+
+      def post_token_exchange(refresh_token)
+        http = Net::HTTP.new(CLAUDE_TOKEN_ENDPOINT.host, CLAUDE_TOKEN_ENDPOINT.port)
+        http.use_ssl = true
+        http.open_timeout = 10
+        http.read_timeout = 10
+
+        request = Net::HTTP::Post.new(CLAUDE_TOKEN_ENDPOINT.path)
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate({
+          grant_type: "refresh_token",
+          refresh_token: refresh_token
+        })
+
+        response = http.request(request)
+
+        body = begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          {}
+        end
+
+        unless response.is_a?(Net::HTTPSuccess)
+          error_code = body["error"] || body["code"]
+          if error_code.to_s.match?(/refresh_token_reused/i)
+            raise AuthenticationError.new(
+              "Refresh token has already been used (refresh_token_reused). Re-authentication required.",
+              provider: :claude
+            )
+          end
+
+          error_description = body["error_description"] || body["message"] || response.body
+          raise AuthenticationError.new(
+            "Token exchange failed (HTTP #{response.code}): #{error_description}",
+            provider: :claude
+          )
+        end
+
+        body
+      end
+
+      # Extract a usable token and expiry from Claude credentials,
+      # supporting both the native claudeAiOauth shape and the legacy
+      # top-level oauth_token/apiKey shape.
+      #
+      # @return [Array(String, Time)] token and parsed expiry, or nils
+      def extract_claude_token(credentials)
+        # Prefer the native claudeAiOauth nested shape written by the Claude CLI
+        if credentials.key?("claudeAiOauth")
+          oauth = credentials["claudeAiOauth"]
+          if oauth.is_a?(Hash)
+            access_token = oauth["accessToken"]
+            if non_blank?(access_token)
+              expires_at = parse_expiry(oauth["expiresAt"])
+              return [access_token, expires_at]
+            end
+          end
+        end
+
+        # Fall back to the legacy top-level shape
+        oauth_token = credentials["oauth_token"]
+        api_key = credentials["apiKey"]
+        token = [oauth_token, api_key].find { |t| non_blank?(t) }
+        expires_at = parse_expiry(credentials["expiresAt"] || credentials["expires_at"]) if token
+        [token, expires_at]
+      end
+
+      def non_blank?(value)
+        value.is_a?(String) && !value.strip.empty?
+      end
+
       def read_claude_credentials
         path = claude_credentials_path
         return nil unless File.exist?(path)

data/lib/agent_harness/version.rb

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

data/lib/agent_harness.rb

@@ -339,6 +339,23 @@ module AgentHarness
       Authentication.refresh_auth(provider_name, token: token)
     end
 
+    # Check whether refresh-token exchange is supported for a provider
+    # @param provider_name [Symbol] the provider name
+    # @return [Boolean] true if exchange_refresh_token can be called
+    # @raise [ProviderNotFoundError] if provider is unknown
+    def exchange_refresh_token_supported?(provider_name)
+      Authentication.exchange_refresh_token_supported?(provider_name)
+    end
+
+    # Exchange a stored refresh token for a fresh access token
+    # @param provider_name [Symbol] the provider name
+    # @return [Hash] credential in claudeAiOauth shape
+    # @raise [UnsupportedAuthFlowError] if provider doesn't support token exchange
+    # @raise [AuthenticationError] if the refresh token is missing, reused, or exchange fails
+    def exchange_refresh_token(provider_name)
+      Authentication.exchange_refresh_token(provider_name)
+    end
+
     # Check health of all configured providers.
     #
     # Validates each enabled provider through registration, CLI availability,

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.25.0
 platform: ruby
 authors:
 - Bart Agapinan