yatfa 1.0.91 → 1.0.92

package/bin/run-yatfa-agent.rb

@@ -13,6 +13,7 @@
 
 require_relative "../lib/yatfa_agent/config"
 require_relative "../lib/yatfa_agent/docker"
+require_relative "../lib/yatfa_agent/http"
 require_relative "../lib/yatfa_agent/agent"
 require_relative "../lib/yatfa_agent/setup"
 require_relative "../lib/yatfa_agent/updater"
@@ -27,12 +28,8 @@ def current_version
 end
 
 def latest_npm_version
-  require "net/http"
-  require "json"
-  uri = URI("https://registry.npmjs.org/yatfa/latest")
-  response = Net::HTTP.get_response(uri)
-  return nil unless response.is_a?(Net::HTTPSuccess)
-  JSON.parse(response.body)["version"]
+  data = YatfaAgent::HTTP.get("https://registry.npmjs.org/yatfa/latest")
+  data&.dig("version")
 rescue StandardError
   nil
 end

package/lib/yatfa_agent/config.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "http"
 
 module YatfaAgent
   module Config
@@ -122,49 +123,54 @@ module YatfaAgent
 
       return unless mcp_api_key
 
-      # First, discover which project we belong to via /whoami
-      require "net/http"
-      require "json"
-      require "uri"
+      auth_headers = { "X-API-Key" => mcp_api_key, "Accept" => "application/json" }
 
-      whoami_uri = URI("#{api_base}/whoami")
-      whoami_response = Net::HTTP.get_response(whoami_uri, { "X-API-Key" => mcp_api_key, "Accept" => "application/json" })
+      # First, discover which project we belong to via /whoami
+      begin
+        agent_info = YatfaAgent::HTTP.get("#{api_base}/whoami", headers: auth_headers)
 
-      if whoami_response.code != "200"
-        puts "⚠️  Unable to discover project from /whoami (HTTP #{whoami_response.code})"
+        # Under the raise-based HTTP contract, a nil result here means an empty
+        # 2xx body (real failures raise YatfaAgent::HTTP::Error below).
+        unless agent_info
+          puts "⚠️  Empty response from /whoami, skipping repository fetch"
+          return
+        end
+      rescue YatfaAgent::HTTP::Error => e
+        puts "⚠️  Unable to discover project from /whoami (HTTP #{e.status_code})"
+        return
+      rescue StandardError => e
+        puts "⚠️  Unable to discover project from /whoami: #{e.message}"
         return
       end
 
-      agent_info = JSON.parse(whoami_response.body)
       project_id = agent_info["project_id"]
       project_name = agent_info["name"] rescue "unknown"
 
       puts "🔑 Authenticated as #{agent_info["name"]} (project #{project_id})"
 
       # Then fetch repositories from Rails API (scoped to our project)
-      uri = URI("#{api_base}/repositories")
       begin
-        response = Net::HTTP.get_response(uri, { "X-API-Key" => mcp_api_key, "Accept" => "application/json" })
-
-        if response.code == "200"
-          repositories = JSON.parse(response.body)
+        repositories = YatfaAgent::HTTP.get("#{api_base}/repositories", headers: auth_headers)
 
-          if repositories.any?
-            config["repositories"] = repositories
+        if repositories.is_a?(Array) && repositories.any?
+          config["repositories"] = repositories
 
-            # Build REPOSITORIES_CONTEXT string: "name:path,name:path"
-            repo_context = repositories.map { |r| "#{r['name']}:#{r['path_in_sandbox']}" }.join(",")
-            config["env"] ||= {}
-            config["env"]["REPOSITORIES_CONTEXT"] = repo_context
+          # Build REPOSITORIES_CONTEXT string: "name:path,name:path"
+          repo_context = repositories.map { |r| "#{r['name']}:#{r['path_in_sandbox']}" }.join(",")
+          config["env"] ||= {}
+          config["env"]["REPOSITORIES_CONTEXT"] = repo_context
 
-            puts "📚 Loaded #{repositories.count} repositories for project #{project_id} (#{project_name})"
-            repositories.each do |repo|
-              puts "   - #{repo['name']}: #{repo['path_in_sandbox']}"
-            end
+          puts "📚 Loaded #{repositories.count} repositories for project #{project_id} (#{project_name})"
+          repositories.each do |repo|
+            puts "   - #{repo['name']}: #{repo['path_in_sandbox']}"
           end
-        else
-          puts "⚠️  Unable to fetch repositories (HTTP #{response.code})"
+        elsif repositories.nil?
+          # Empty 2xx body — the raise-based contract returns nil only then.
+          puts "⚠️  Empty response when fetching repositories"
         end
+        # An empty Array ([]) means no repositories are configured; nothing to do.
+      rescue YatfaAgent::HTTP::Error => e
+        puts "⚠️  Failed to fetch repositories (HTTP #{e.status_code})"
       rescue StandardError => e
         puts "⚠️  Failed to fetch repositories: #{e.message}"
       end

package/lib/yatfa_agent/docker.rb

@@ -1,10 +1,9 @@
 # frozen_string_literal: true
 
 require "fileutils"
-require "net/http"
 require "json"
 require "time"
-require "uri"
+require_relative "http"
 
 module YatfaAgent
   module Docker
@@ -24,12 +23,16 @@ module YatfaAgent
     end
 
     def self.fetch_remote_version
-      uri = URI(VERSION_URL)
-      response = Net::HTTP.get_response(uri)
-      return nil unless response.is_a?(Net::HTTPSuccess)
-      data = JSON.parse(response.body)
-      data["version"]
-    rescue StandardError
+      data = YatfaAgent::HTTP.get(VERSION_URL)
+      data&.dig("version")
+    rescue YatfaAgent::HTTP::Error => e
+      # Non-2xx response: surface the status so a version-fetch failure is
+      # distinguishable from "no remote update" (which returns nil on a 2xx).
+      warn "⚠️  Remote version check failed (HTTP #{e.status_code})"
+      nil
+    rescue StandardError => e
+      # Genuine network/timeout error (no HTTP status code available).
+      warn "⚠️  Remote version check failed (#{e.class}: #{e.message})"
       nil
     end
 

package/lib/yatfa_agent/http.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module YatfaAgent
+  module HTTP
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 10
+
+    # Custom error for HTTP failures with response details.
+    # Raised for non-2xx responses so callers can access status code and body.
+    class Error < StandardError
+      attr_reader :status_code, :response_body
+
+      # @param message [String] error message (e.g., "HTTP 401 Unauthorized")
+      # @param status_code [Integer] HTTP status code
+      # @param response_body [String] raw response body
+      def initialize(message, status_code:, response_body:)
+        super(message)
+        @status_code = status_code
+        @response_body = response_body
+      end
+    end
+
+    # Perform a GET request. Returns parsed JSON body on success.
+    # Raises YatfaAgent::HTTP::Error for non-2xx responses.
+    # Raises exceptions on network/timeout errors.
+    #
+    # @param url [String] full URL to request
+    # @param headers [Hash] HTTP headers (e.g., { "X-API-Key" => "key" })
+    # @param open_timeout [Integer] connection timeout in seconds (default: 5)
+    # @param read_timeout [Integer] response timeout in seconds (default: 10)
+    # @return [Hash, Array, nil] parsed JSON response, or nil for empty 2xx responses
+    # @raise [Error] for non-2xx HTTP responses
+    def self.get(url, headers: {}, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+      uri = URI(url)
+      http = build_http(uri, open_timeout: open_timeout, read_timeout: read_timeout)
+      request = Net::HTTP::Get.new(uri)
+      headers.each { |k, v| request[k] = v }
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    # Perform a POST request. Returns parsed JSON body on success.
+    # Raises YatfaAgent::HTTP::Error for non-2xx responses.
+    # Raises exceptions on network/timeout errors.
+    #
+    # @param url [String] full URL to request
+    # @param body [Hash, String] request body (Hash is auto-serialized to JSON)
+    # @param headers [Hash] HTTP headers
+    # @param open_timeout [Integer] connection timeout in seconds (default: 5)
+    # @param read_timeout [Integer] response timeout in seconds (default: 10)
+    # @return [Hash, Array, nil] parsed JSON response, or nil for empty 2xx responses
+    # @raise [Error] for non-2xx HTTP responses
+    def self.post(url, body:, headers: {}, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+      uri = URI(url)
+      http = build_http(uri, open_timeout: open_timeout, read_timeout: read_timeout)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json" unless headers.key?("Content-Type")
+      headers.each { |k, v| request[k] = v }
+      request.body = body.is_a?(String) ? body : JSON.generate(body)
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    class << self
+      private
+
+      def build_http(uri, open_timeout:, read_timeout:)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = open_timeout
+        http.read_timeout = read_timeout
+        http
+      end
+
+      def parse_json(body)
+        return nil if body.nil? || body.empty?
+        JSON.parse(body)
+      end
+
+      def handle_response(response)
+        if response.is_a?(Net::HTTPSuccess)
+          parse_json(response.body)
+        else
+          raise Error.new(
+            "HTTP #{response.code} #{response.message}",
+            status_code: response.code.to_i,
+            response_body: response.body
+          )
+        end
+      end
+    end
+  end
+end

package/lib/yatfa_agent/setup.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
-require "net/http"
 require "uri"
 require "json"
 require "readline"
 require "fileutils"
+require_relative "http"
 
 module YatfaAgent
   module Setup
@@ -581,21 +581,25 @@ module YatfaAgent
       # Helper methods
 
       def validate_api_key(api_key, yatfa_url)
-        # Derive API URL
         api_base = "#{yatfa_url}/api/v1"
-        uri = URI("#{api_base}/whoami")
-
-        begin
-          response = Net::HTTP.get_response(
-            uri,
-            { "X-API-Key" => api_key, "Accept" => "application/json" }
-          )
-
-          response.code == "200"
-        rescue StandardError => e
-          @errors << "API key validation failed: #{e.message}"
-          false
+        result = YatfaAgent::HTTP.get(
+          "#{api_base}/whoami",
+          headers: { "X-API-Key" => api_key, "Accept" => "application/json" }
+        )
+        !result.nil?
+      rescue YatfaAgent::HTTP::Error => e
+        case e.status_code
+        when 401, 403
+          @errors << "API key is invalid or unauthorized (HTTP #{e.status_code})"
+        when 500..599
+          @errors << "Yatfa server returned HTTP #{e.status_code}; service may be unavailable, please retry"
+        else
+          @errors << "API key validation failed (HTTP #{e.status_code})"
         end
+        false
+      rescue StandardError => e
+        @errors << "API key validation failed: #{e.message}"
+        false
       end
 
       def validate_github_credentials
@@ -625,16 +629,25 @@ module YatfaAgent
 
         # If gh CLI is not configured, try direct API call
         unless status.success?
-          uri = URI("https://api.github.com/user")
-          response = Net::HTTP.get_response(
-            uri,
-            { "Authorization" => "Bearer #{token}", "Accept" => "application/json" }
+          result = YatfaAgent::HTTP.get(
+            "https://api.github.com/user",
+            headers: { "Authorization" => "Bearer #{token}", "Accept" => "application/json" }
           )
 
-          return response.code == "200"
+          return !result.nil?
         end
 
         true
+      rescue YatfaAgent::HTTP::Error => e
+        case e.status_code
+        when 401, 403
+          @errors << "GitHub token is invalid or unauthorized (HTTP #{e.status_code})"
+        when 500..599
+          @errors << "GitHub API returned HTTP #{e.status_code}; service may be unavailable, please retry"
+        else
+          @errors << "GitHub token validation failed (HTTP #{e.status_code})"
+        end
+        false
       end
 
       def validate_github_app

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "yatfa",
-  "version": "1.0.91",
+  "version": "1.0.92",
   "description": "YATFA - Yet Another Tool For Agents",
   "bin": "./bin/run-yatfa-agent.rb",
   "files": [

package/setup/agent_bridge.rb

@@ -42,8 +42,8 @@ def download_agent_bridge!
     local_override = File.join(override_dir, "agent-bridge-linux-#{arch}")
     if File.exist?(local_override)
       puts "🔧 Using local override: #{local_override}"
-      system("sudo cp #{local_override} #{target_dir}/agent-bridge")
-      system("sudo chmod +x #{target_dir}/agent-bridge")
+      system("sudo", "cp", local_override, "#{target_dir}/agent-bridge")
+      system("sudo", "chmod", "+x", "#{target_dir}/agent-bridge")
       puts "✅ agent-bridge installed from local override"
       return download_agent_bridge_tmux!(target_dir)
     end
@@ -52,8 +52,8 @@ def download_agent_bridge!
   # 2. Check if binaries are mounted at /tmp (dev mode)
   if File.exist?("/tmp/agent-bridge")
     puts "🔧 Installing mounted agent-bridge..."
-    system("sudo cp /tmp/agent-bridge #{target_dir}/agent-bridge")
-    system("sudo chmod +x #{target_dir}/agent-bridge")
+    system("sudo", "cp", "/tmp/agent-bridge", "#{target_dir}/agent-bridge")
+    system("sudo", "chmod", "+x", "#{target_dir}/agent-bridge")
     puts "✅ agent-bridge installed from mount"
     return download_agent_bridge_tmux!(target_dir)
   end
@@ -71,8 +71,8 @@ def download_agent_bridge!
   # 4. Fallback to GitHub raw URLs (legacy)
   bridge_url = "#{YATFA_RAW_URL}/bin/agent-bridge-linux-#{arch}"
   puts "📥 Downloading agent-bridge for linux-#{arch} from GitHub..."
-  system("sudo curl -fsSL #{bridge_url} -o #{target_dir}/agent-bridge")
-  system("sudo chmod +x #{target_dir}/agent-bridge")
+  system("sudo", "curl", "-fsSL", bridge_url, "-o", "#{target_dir}/agent-bridge")
+  system("sudo", "chmod", "+x", "#{target_dir}/agent-bridge")
 
   puts "✅ agent-bridge installed to #{target_dir}"
   download_agent_bridge_tmux!(target_dir)
@@ -119,7 +119,7 @@ def download_from_civo!(arch, target_dir)
       return false
     end
 
-    system("sudo chmod +x #{target_dir}/agent-bridge")
+    system("sudo", "chmod", "+x", "#{target_dir}/agent-bridge")
     puts "✅ Downloaded agent-bridge from Civo"
     return true
 
@@ -140,11 +140,11 @@ def download_agent_bridge_tmux!(target_dir)
 
   if File.exist?("/tmp/agent-bridge-tmux")
     puts "🔧 Installing mounted agent-bridge-tmux..."
-    system("sudo cp /tmp/agent-bridge-tmux #{target_dir}/agent-bridge-tmux")
-    system("sudo chmod +x #{target_dir}/agent-bridge-tmux")
+    system("sudo", "cp", "/tmp/agent-bridge-tmux", "#{target_dir}/agent-bridge-tmux")
+    system("sudo", "chmod", "+x", "#{target_dir}/agent-bridge-tmux")
   else
-    system("sudo curl -fsSL #{bridge_tmux_url} -o #{target_dir}/agent-bridge-tmux")
-    system("sudo chmod +x #{target_dir}/agent-bridge-tmux")
+    system("sudo", "curl", "-fsSL", bridge_tmux_url, "-o", "#{target_dir}/agent-bridge-tmux")
+    system("sudo", "chmod", "+x", "#{target_dir}/agent-bridge-tmux")
   end
 
   # Patch agent-bridge-tmux to force INSIDE_TMUX=1
@@ -166,8 +166,8 @@ def download_agent_bridge_tmux!(target_dir)
     File.write("/tmp/agent-bridge-tmux-patched", new_content)
 
     # Move to destination with sudo
-    system("sudo mv /tmp/agent-bridge-tmux-patched #{target_dir}/agent-bridge-tmux")
-    system("sudo chmod +x #{target_dir}/agent-bridge-tmux")
+    system("sudo", "mv", "/tmp/agent-bridge-tmux-patched", "#{target_dir}/agent-bridge-tmux")
+    system("sudo", "chmod", "+x", "#{target_dir}/agent-bridge-tmux")
   end
 
   return target_dir
@@ -186,8 +186,8 @@ def install_helper_script(bin_dir, script_name)
   target = File.join(bin_dir, script_name)
   temp_script = "/tmp/#{script_name}.temp"
   File.write(temp_script, script_content)
-  system("sudo mv #{temp_script} #{target}")
-  system("sudo chmod +x #{target}")
+  system("sudo", "mv", temp_script, target)
+  system("sudo", "chmod", "+x", target)
   puts "✅ Installed #{script_name} to #{bin_dir}"
   true
 end

package/setup/claude_settings.rb

@@ -24,37 +24,35 @@ def fetch_llm_credentials!
     return nil
   end
 
-  # Fetch LLM credentials from Rails API
-  uri = URI("#{rails_api_url}/llm/credentials")
-  http = Net::HTTP.new(uri.host, uri.port)
-  http.use_ssl = uri.scheme == "https"
-  http.open_timeout = 10
-  http.read_timeout = 10
-
-  request = Net::HTTP::Get.new(uri)
-  request["X-API-Key"] = rails_api_key
-  request["Accept"] = "application/json"
-
   begin
     puts "🔍 Fetching LLM credentials from #{rails_api_url}/llm/credentials..."
-    response = http.request(request)
-
-    if response.is_a?(Net::HTTPSuccess)
-      data = JSON.parse(response.body)
-      puts "✅ LLM credentials fetched successfully"
-      data
-    elsif response.is_a?(Net::HTTPNotFound)
-      puts "❌ No LLM credentials configured in backend"
-      nil
+    data = YatfaAgent::HTTP.get(
+      "#{rails_api_url}/llm/credentials",
+      headers: { "X-API-Key" => rails_api_key, "Accept" => "application/json" },
+      open_timeout: 10,
+      read_timeout: 10
+    )
+
+    # Under the raise-based HTTP contract, a nil result means an empty 2xx body
+    # (real failures raise YatfaAgent::HTTP::Error below).
+    unless data
+      puts "❌ Empty response from /llm/credentials; no LLM credentials configured"
+      return nil
+    end
+
+    puts "✅ LLM credentials fetched successfully"
+    data
+  rescue YatfaAgent::HTTP::Error => e
+    case e.status_code
+    when 401, 403
+      puts "❌ Yatfa API key or token is invalid or unauthorized (HTTP #{e.status_code})"
+    when 500..599
+      puts "❌ Yatfa server returned HTTP #{e.status_code}; service may be unavailable, please retry"
     else
-      puts "❌ Failed to fetch LLM credentials: #{response.code} #{response.message}"
-      puts "   Response: #{response.body}"
-      nil
+      puts "❌ Failed to fetch LLM credentials (HTTP #{e.status_code})"
     end
-  rescue Net::OpenTimeout, Net::ReadTimeout => e
-    puts "❌ Timeout fetching LLM credentials: #{e.message}"
     nil
-  rescue => e
+  rescue StandardError => e
     puts "❌ Error fetching LLM credentials: #{e.message}"
     nil
   end
@@ -123,6 +121,15 @@ def setup_claude_settings!
   hooks_dir = File.join(settings_dir, "hooks")
   FileUtils.mkdir_p(hooks_dir)
 
+  # Download shared HTTP client for hook scripts
+  download_file(
+    script_name: "http_client.rb",
+    remote_url: "#{YATFA_RAW_URL}/hooks/http_client.rb",
+    dest_dir: hooks_dir,
+    executable: false,
+    label: "HTTP client helper"
+  )
+
   # SessionStart hook: skill knowledge injection
   install_hook!(
     settings_config, hooks_dir,

package/setup/http_client.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module YatfaAgent
+  module HTTP
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 10
+
+    # Custom error for HTTP failures with response details.
+    # Raised for non-2xx responses so callers can access status code and body.
+    class Error < StandardError
+      attr_reader :status_code, :response_body
+
+      # @param message [String] error message (e.g., "HTTP 401 Unauthorized")
+      # @param status_code [Integer] HTTP status code
+      # @param response_body [String] raw response body
+      def initialize(message, status_code:, response_body:)
+        super(message)
+        @status_code = status_code
+        @response_body = response_body
+      end
+    end
+
+    # Perform a GET request. Returns parsed JSON body on success.
+    # Raises YatfaAgent::HTTP::Error for non-2xx responses.
+    # Raises exceptions on network/timeout errors.
+    #
+    # @param url [String] full URL to request
+    # @param headers [Hash] HTTP headers (e.g., { "X-API-Key" => "key" })
+    # @param open_timeout [Integer] connection timeout in seconds (default: 5)
+    # @param read_timeout [Integer] response timeout in seconds (default: 10)
+    # @return [Hash, Array, nil] parsed JSON response, or nil for empty 2xx responses
+    # @raise [Error] for non-2xx HTTP responses
+    def self.get(url, headers: {}, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+      uri = URI(url)
+      http = build_http(uri, open_timeout: open_timeout, read_timeout: read_timeout)
+      request = Net::HTTP::Get.new(uri)
+      headers.each { |k, v| request[k] = v }
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    # Perform a POST request. Returns parsed JSON body on success.
+    # Raises YatfaAgent::HTTP::Error for non-2xx responses.
+    # Raises exceptions on network/timeout errors.
+    #
+    # @param url [String] full URL to request
+    # @param body [Hash, String] request body (Hash is auto-serialized to JSON)
+    # @param headers [Hash] HTTP headers
+    # @param open_timeout [Integer] connection timeout in seconds (default: 5)
+    # @param read_timeout [Integer] response timeout in seconds (default: 10)
+    # @return [Hash, Array, nil] parsed JSON response, or nil for empty 2xx responses
+    # @raise [Error] for non-2xx HTTP responses
+    def self.post(url, body:, headers: {}, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+      uri = URI(url)
+      http = build_http(uri, open_timeout: open_timeout, read_timeout: read_timeout)
+      request = Net::HTTP::Post.new(uri)
+      request["Content-Type"] = "application/json" unless headers.key?("Content-Type")
+      headers.each { |k, v| request[k] = v }
+      request.body = body.is_a?(String) ? body : JSON.generate(body)
+      response = http.request(request)
+      handle_response(response)
+    end
+
+    class << self
+      private
+
+      def build_http(uri, open_timeout:, read_timeout:)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = open_timeout
+        http.read_timeout = read_timeout
+        http
+      end
+
+      def parse_json(body)
+        return nil if body.nil? || body.empty?
+        JSON.parse(body)
+      end
+
+      def handle_response(response)
+        if response.is_a?(Net::HTTPSuccess)
+          parse_json(response.body)
+        else
+          raise Error.new(
+            "HTTP #{response.code} #{response.message}",
+            status_code: response.code.to_i,
+            response_body: response.body
+          )
+        end
+      end
+    end
+  end
+end

package/setup/setup-agent.rb

@@ -30,12 +30,12 @@ require "fileutils"
 require "pathname"
 require "open-uri"
 require "openssl"
-require "net/http"
 require "uri"
 require "base64"
 require "time"
 require "socket"
 require "timeout"
+require_relative "http_client"
 require_relative "setup-github"
 require_relative "repositories"
 require_relative "agent_bridge"
@@ -126,36 +126,37 @@ def fetch_agent_id!
   whoami_url = "#{rails_api_url}/whoami"
   whoami_url += "?version=#{URI.encode_www_form_component(agent_version)}" if agent_version && !agent_version.empty?
 
-  uri = URI(whoami_url)
-  http = Net::HTTP.new(uri.host, uri.port)
-  http.use_ssl = uri.scheme == "https"
-
-  request = Net::HTTP::Get.new(uri)
-  request["X-API-Key"] = rails_api_key
-  request["Accept"] = "application/json"
-
   begin
     puts "🔍 Fetching agent ID from #{rails_api_url}/whoami..."
-    response = http.request(request)
-
-    if response.is_a?(Net::HTTPSuccess)
-      data = JSON.parse(response.body)
-      agent_id = data["agent_id"] || data["id"]
-
-      if agent_id && !agent_id.to_s.empty?
-        ENV["AGENT_ID"] = agent_id.to_s
-        puts "✅ Agent ID fetched: #{agent_id}"
-      else
-        puts "❌ Could not find agent_id in API response"
-        puts "   Response: #{response.body}"
-        exit 1
-      end
+    data = YatfaAgent::HTTP.get(whoami_url, headers: { "X-API-Key" => rails_api_key, "Accept" => "application/json" })
+
+    # Under the raise-based HTTP contract, a nil result means an empty 2xx body
+    # (real failures raise YatfaAgent::HTTP::Error below).
+    unless data
+      puts "❌ Empty response from /whoami; cannot determine agent ID"
+      exit 1
+    end
+
+    agent_id = data["agent_id"] || data["id"]
+
+    if agent_id && !agent_id.to_s.empty?
+      ENV["AGENT_ID"] = agent_id.to_s
+      puts "✅ Agent ID fetched: #{agent_id}"
     else
-      puts "❌ Failed to fetch agent ID: #{response.code} #{response.message}"
-      puts "   Response: #{response.body}"
+      puts "❌ Could not find agent_id in API response"
       exit 1
     end
-  rescue => e
+  rescue YatfaAgent::HTTP::Error => e
+    case e.status_code
+    when 401, 403
+      puts "❌ Yatfa API key or token is invalid or unauthorized (HTTP #{e.status_code})"
+    when 500..599
+      puts "❌ Yatfa server returned HTTP #{e.status_code}; service may be unavailable, please retry"
+    else
+      puts "❌ Failed to fetch agent ID (HTTP #{e.status_code})"
+    end
+    exit 1
+  rescue StandardError => e
     puts "❌ Error fetching agent ID: #{e.message}"
     puts "   #{e.class}: #{e.backtrace.first}"
     exit 1
@@ -191,7 +192,7 @@ def setup_mcp_config!
 
     puts "📦 Installing yatfa-mcp..."
     # Redirect output to avoid cluttering logs, unless it fails
-    unless system("npm install --prefix #{tools_dir} yatfa-mcp > /dev/null 2>&1")
+    unless system("npm", "install", "--prefix", tools_dir, "yatfa-mcp", out: "/dev/null", err: "/dev/null")
       puts "❌ Failed to install yatfa-mcp"
     end
 
@@ -261,7 +262,7 @@ def setup_git_config!
 
   # Avoid "dubious ownership" errors in containers
   # Note: Individual repository paths are added in clone_repositories! after cloning
-  system("git config --global --add safe.directory \"#{Dir.pwd}\"")
+  system("git", "config", "--global", "--add", "safe.directory", Dir.pwd)
   puts "✅ Git configured to trust #{Dir.pwd}"
 end
 
@@ -308,30 +309,33 @@ end
 # ─── Main ─────────────────────────────────────────────────────────────────
 
 # Main
-puts "🤖 Yatfa Agent Setup"
-puts "====================="
-puts ""
-
-# Claw agent has its own completely separate setup flow
-if ENV["AGENT_TYPE"] == "claw"
-  require_relative "setup-claw-agent"
-else
-  check_env!
-  fetch_agent_id!
-  setup_mcp_config!
-  setup_system_prompt!
-  # Clone repositories BEFORE setting up hooks that depend on them
-  setup_github_auth!
-  setup_git_config!
-  clone_repositories!
-  setup_claude_config!
-  setup_claude_settings!
-  # setup_skill_hooks! # Deprecated in favor of global hooks
-  setup_skills!
-  setup_community_skills!
-  setup_git_hooks!
-  setup_helper_scripts!
-  # prepare_git_state! is now in entrypoint.sh
-  bin_dir = download_agent_bridge!
-  run_agent!(bin_dir)
+if __FILE__ == $PROGRAM_NAME
+  puts "🤖 Yatfa Agent Setup"
+  puts "====================="
+  puts ""
+
+  # Claw agent has its own completely separate setup flow
+  if ENV["AGENT_TYPE"] == "claw"
+    require_relative "setup-claw-agent"
+    setup_claw_agent!
+  else
+    check_env!
+    fetch_agent_id!
+    setup_mcp_config!
+    setup_system_prompt!
+    # Clone repositories BEFORE setting up hooks that depend on them
+    setup_github_auth!
+    setup_git_config!
+    clone_repositories!
+    setup_claude_config!
+    setup_claude_settings!
+    # setup_skill_hooks! # Deprecated in favor of global hooks
+    setup_skills!
+    setup_community_skills!
+    setup_git_hooks!
+    setup_helper_scripts!
+    # prepare_git_state! is now in entrypoint.sh
+    bin_dir = download_agent_bridge!
+    run_agent!(bin_dir)
+  end
 end

package/setup/setup-claw-agent.rb

@@ -93,7 +93,7 @@ def install_openclaw!
   # Fix ownership of ~/.openclaw if sudo created it as root
   openclaw_dir = File.expand_path("~/.openclaw")
   if File.exist?(openclaw_dir) && Process.uid != 0
-    system("sudo chown -R #{Process.uid}:#{Process.gid} #{openclaw_dir} 2>/dev/null")
+    system("sudo", "chown", "-R", "#{Process.uid}:#{Process.gid}", openclaw_dir, err: "/dev/null")
   end
 end
 
@@ -249,22 +249,7 @@ def setup_yatfa_tools_for_claw!
   # Fetch tool definitions from Rails now (during setup) so the plugin can
   # register them synchronously — register() must NOT be async.
   tool_defs_json = File.join(ext_dir, "tools.json")
-  begin
-    uri = URI("#{yatfa_api_url}/mcp/tools")
-    req = Net::HTTP::Get.new(uri)
-    req["Content-Type"] = "application/json"
-    req["X-API-Key"] = yatfa_api_key
-    req["Accept"] = "application/json"
-    http = Net::HTTP.new(uri.host, uri.port)
-    http.use_ssl = uri.scheme == "https"
-    resp = http.request(req)
-    tools_data = JSON.parse(resp.body)
-    File.write(tool_defs_json, JSON.pretty_generate(tools_data["tools"] || []))
-    puts "✅ Fetched #{(tools_data["tools"] || []).length} tool definitions from Yatfa API"
-  rescue => e
-    puts "⚠️  Failed to fetch tool definitions: #{e.message}"
-    File.write(tool_defs_json, "[]")
-  end
+  fetch_tool_definitions!(yatfa_api_url: yatfa_api_url, yatfa_api_key: yatfa_api_key, dest_path: tool_defs_json)
 
   File.write(plugin_js, <<~JS)
     import { t as definePluginEntry } from "#{rel_path}/#{plugin_entry_file}";
@@ -402,6 +387,38 @@ def setup_yatfa_tools_for_claw!
   puts "✅ yatfa-bridge skill installed to #{skills_dir}"
 end
 
+# Fetch MCP tool definitions from the Yatfa backend and write them to +dest_path+
+# as a JSON array. Called during claw setup so the OpenClaw plugin can register
+# tools synchronously.
+#
+# Under the raise-based HTTP contract, a nil tools_data means an empty 2xx body
+# (real failures raise YatfaAgent::HTTP::Error below). On any failure the
+# destination is still written as "[]" so the plugin can boot with no tools.
+def fetch_tool_definitions!(yatfa_api_url:, yatfa_api_key:, dest_path:)
+  tools_data = YatfaAgent::HTTP.get(
+    "#{yatfa_api_url}/mcp/tools",
+    headers: { "Content-Type" => "application/json", "X-API-Key" => yatfa_api_key, "Accept" => "application/json" }
+  )
+
+  # Empty 2xx body — raise-based contract returns nil only then.
+  tools_list = tools_data&.dig("tools") || []
+  File.write(dest_path, JSON.pretty_generate(tools_list))
+  puts "✅ Fetched #{tools_list.length} tool definitions from Yatfa API"
+rescue YatfaAgent::HTTP::Error => e
+  case e.status_code
+  when 401, 403
+    puts "⚠️  Yatfa API key or token is invalid or unauthorized (HTTP #{e.status_code})"
+  when 500..599
+    puts "⚠️  Yatfa server returned HTTP #{e.status_code}; service may be unavailable, please retry"
+  else
+    puts "⚠️  Failed to fetch tool definitions (HTTP #{e.status_code})"
+  end
+  File.write(dest_path, "[]")
+rescue StandardError => e
+  puts "⚠️  Failed to fetch tool definitions: #{e.message}"
+  File.write(dest_path, "[]")
+end
+
 def run_openclaw_gateway!
   port = ENV["OPENCLAW_PORT"] || "18789"
 
@@ -491,4 +508,11 @@ end
 
 # ─── Main ─────────────────────────────────────────────────────────────────
 
-setup_claw_agent!
+# This file is normally required by setup-agent.rb, which invokes
+# setup_claw_agent! explicitly (see the claw branch there). The guard below
+# preserves `ruby setup-claw-agent.rb` as a direct entry point while letting
+# the file be required as a library (e.g. by the spec suite) without
+# auto-running setup.
+if __FILE__ == $PROGRAM_NAME
+  setup_claw_agent!
+end

package/setup/setup-github.rb

@@ -116,8 +116,8 @@ def setup_github_auth!
     # Install helper via sudo to /usr/local/bin
     helper_path = "/usr/local/bin/git-auth-helper"
     File.write("/tmp/git-auth-helper", helper_content)
-    system("sudo mv /tmp/git-auth-helper #{helper_path}")
-    system("sudo chmod +x #{helper_path}")
+    system("sudo", "mv", "/tmp/git-auth-helper", helper_path)
+    system("sudo", "chmod", "+x", helper_path)
 
     # Configure git (array form avoids shell interpolation of helper path)
     system("git", "config", "--global", "credential.helper", "!f() { test \"$1\" = get && echo \"protocol=https\" && echo \"host=github.com\" && echo \"username=x-access-token\" && p=$(#{helper_path}) && echo \"password=$p\"; }; f")
@@ -167,7 +167,7 @@ def install_gh_wrapper!(real_gh_path:, with_token_refresh: false, token_helper_p
 
   # Move real gh to gh.real if not already done
   unless File.exist?("#{real_gh_path}.real")
-    system("sudo mv #{real_gh_path} #{real_gh_path}.real")
+    system("sudo", "mv", real_gh_path, "#{real_gh_path}.real")
   end
 
   wrapper_path = "/usr/local/bin/gh"
@@ -224,7 +224,7 @@ def install_gh_wrapper!(real_gh_path:, with_token_refresh: false, token_helper_p
   BASH
 
   File.write("/tmp/gh-wrapper", wrapper_content)
-  system("sudo mv /tmp/gh-wrapper #{wrapper_path}")
-  system("sudo chmod +x #{wrapper_path}")
+  system("sudo", "mv", "/tmp/gh-wrapper", wrapper_path)
+  system("sudo", "chmod", "+x", wrapper_path)
   true
 end

package/setup/skills.rb

@@ -61,28 +61,35 @@ def fetch_community_skills!
     return []
   end
 
-  uri = URI("#{rails_api_url}/whoami")
-  http = Net::HTTP.new(uri.host, uri.port)
-  http.use_ssl = uri.scheme == "https"
-
-  request = Net::HTTP::Get.new(uri)
-  request["X-API-Key"] = rails_api_key
-  request["Accept"] = "application/json"
-
   begin
-    response = http.request(request)
-    if response.is_a?(Net::HTTPSuccess)
-      data = JSON.parse(response.body)
-      skills = data["community_skills"] || []
-      if skills.any?
-        puts "📦 Found #{skills.size} community skills: #{skills.join(', ')}"
-      end
-      skills
+    data = YatfaAgent::HTTP.get(
+      "#{rails_api_url}/whoami",
+      headers: { "X-API-Key" => rails_api_key, "Accept" => "application/json" }
+    )
+
+    # Under the raise-based HTTP contract, a nil result means an empty 2xx body
+    # (real failures raise YatfaAgent::HTTP::Error below).
+    unless data
+      puts "⚠️  Empty response from /whoami; no community skills configured"
+      return []
+    end
+
+    skills = data["community_skills"] || []
+    if skills.any?
+      puts "📦 Found #{skills.size} community skills: #{skills.join(', ')}"
+    end
+    skills
+  rescue YatfaAgent::HTTP::Error => e
+    case e.status_code
+    when 401, 403
+      puts "⚠️  Yatfa API key or token is invalid or unauthorized (HTTP #{e.status_code})"
+    when 500..599
+      puts "⚠️  Yatfa server returned HTTP #{e.status_code}; service may be unavailable, please retry"
     else
-      puts "⚠️  Could not fetch community skills: #{response.code}"
-      []
+      puts "⚠️  Failed to fetch community skills (HTTP #{e.status_code})"
     end
-  rescue => e
+    []
+  rescue StandardError => e
     puts "⚠️  Error fetching community skills: #{e.message}"
     []
   end

package/setup/system_prompt.rb

@@ -28,41 +28,45 @@ def setup_system_prompt!
   # Fetch system prompt from yatfa API
   # Agent prompts are stored in yatfa/prompts/<agent-type>/base.md
   # and loaded into the database by AgentPromptLoader
-  prompt_url = URI("#{rails_api_url}/internal/skill?tags%5B%5D=#{agent_type}&tags%5B%5D=base")
-  http = Net::HTTP.new(prompt_url.host, prompt_url.port)
-  http.use_ssl = prompt_url.scheme == "https"
-  http.open_timeout = 10
-  http.read_timeout = 15
-
-  request = Net::HTTP::Get.new(prompt_url)
-  request["X-API-Key"] = rails_api_key
-  request["Accept"] = "application/json"
+  prompt_url = "#{rails_api_url}/internal/skill?tags%5B%5D=#{agent_type}&tags%5B%5D=base"
 
   banner_content = nil
   begin
     puts "📥 Fetching system prompt for #{agent_type}..."
-    response = http.request(request)
+    data = YatfaAgent::HTTP.get(
+      prompt_url,
+      headers: { "X-API-Key" => rails_api_key, "Accept" => "application/json" },
+      open_timeout: 10,
+      read_timeout: 15
+    )
+
+    # Under the raise-based HTTP contract, a nil result means an empty 2xx body
+    # (real failures raise YatfaAgent::HTTP::Error below).
+    unless data
+      puts "❌ Empty response from system-prompt endpoint"
+      puts "   Make sure AgentPromptLoader has loaded prompts/ directory"
+      exit 1
+    end
 
-    if response.is_a?(Net::HTTPSuccess)
-      data = JSON.parse(response.body)
-      banner_content = data["content"]
+    banner_content = data["content"]
 
-      unless banner_content && !banner_content.empty?
-        puts "❌ System prompt for '#{agent_type}' is empty"
-        exit 1
-      end
+    unless banner_content && !banner_content.empty?
+      puts "❌ System prompt for '#{agent_type}' is empty"
+      exit 1
+    end
 
-      puts "✅ Fetched system prompt for #{agent_type}"
+    puts "✅ Fetched system prompt for #{agent_type}"
+  rescue YatfaAgent::HTTP::Error => e
+    case e.status_code
+    when 401, 403
+      puts "❌ Yatfa API key or token is invalid or unauthorized (HTTP #{e.status_code})"
+    when 500..599
+      puts "❌ Yatfa server returned HTTP #{e.status_code}; service may be unavailable, please retry"
     else
-      puts "❌ Failed to fetch system prompt: #{response.code} #{response.message}"
-      puts "   Response: #{response.body}"
-      puts "   Make sure AgentPromptLoader has loaded prompts/ directory"
-      exit 1
+      puts "❌ Failed to fetch system prompt (HTTP #{e.status_code})"
     end
-  rescue Net::OpenTimeout, Net::ReadTimeout => e
-    puts "❌ Timeout fetching system prompt: #{e.message}"
     exit 1
-  rescue => e
+  rescue StandardError => e
     puts "❌ Error fetching system prompt: #{e.message}"
     exit 1
   end