yatfa 1.0.98 → 1.0.99

package/bin/run-yatfa-agent.rb

@@ -154,12 +154,12 @@ if command == "attach"
   puts ""
   agent_type = ARGV[1]&.downcase
   abort "Usage: npx yatfa attach [agent-type]" unless agent_type
-  config = YatfaAgent::Config.load
+  config = YatfaAgent::Config.load(allow_remote_fetch: true)
   YatfaAgent::Config.fetch_repositories!(config)
   YatfaAgent::Agent.attach(agent_type, config, AGENT_CONFIGS)
 else
   # Handle run commands (worker, planner, reviewer, researcher, claw)
-  config = YatfaAgent::Config.load
+  config = YatfaAgent::Config.load(allow_remote_fetch: true)
   # Fetch repositories from Rails API before building
   YatfaAgent::Config.fetch_repositories!(config)
   # Note: Docker.build_image is called inside Agent.run() only when a new

package/lib/yatfa_agent/bootstrap.rb

@@ -0,0 +1,389 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require_relative "http"
+
+module YatfaAgent
+  # Single-purpose runner bootstrap (YATFA-3203 / Creation→FULL WORK phase 7b —
+  # runner half).
+  #
+  # Lets a runner in a fresh checkout with no local +yatfa.env.rb+ obtain one
+  # by pasting a single bootstrap string (+<host>#<yrt_token>+), generated by
+  # the server (phase 7a, YATFA-3194). The token authorizes EXACTLY one read —
+  # +GET <host>/api/v1/bootstrap/env_file+ — and is:
+  #   - NOT written into the served +yatfa.env.rb+,
+  #   - NOT exported into runtime env,
+  #   - NOT sent anywhere except the bootstrap endpoint.
+  # (spec YATFA-3019 §2.3 single-purpose invariant — see the comment at
+  # +fetch_remote_env_file+.)
+  #
+  # The {host, token} pair is cached under +~/.yatfa/runner_bootstrap.json+
+  # (0600) so subsequent fresh checkouts auto-fetch without re-prompting — the
+  # credential is single-purpose and read-only, equivalent to +~/.npmrc+. The
+  # cache stores the bootstrap CREDENTIAL, never the env-file CONTENT (each
+  # checkout fetches fresh so rotated keys / new agents propagate).
+  module Bootstrap
+    # Raw token shape: +yrt_+ prefix + 64 hex chars (256 bits). Mirrors the
+    # server's +ProjectRunnerToken.well_formed?+ regex so a malformed paste is
+    # rejected client-side with a friendly error before any network call.
+    TOKEN_PATTERN = /\Ayrt_[0-9a-f]{64}\z/.freeze
+
+    # The single endpoint this credential authorizes a read against.
+    ENV_FILE_PATH = "/api/v1/bootstrap/env_file".freeze
+
+    # Reuses the installer's +~/.yatfa/+ directory convention (installer.rb).
+    # Resolved at call time (methods, not load-time constants) so the path
+    # tracks the current +HOME+ — keeps the cache location correct under
+    # env changes and lets specs isolate it via +ENV["HOME"]+.
+    def self.cache_dir
+      File.expand_path("~/.yatfa")
+    end
+
+    def self.cache_file
+      File.join(cache_dir, "runner_bootstrap.json")
+    end
+    private_class_method :cache_dir, :cache_file
+
+    # Parsed paste string: either a valid {host, token} pair or an {error}
+    # message. Never echoes the token in +error+. Use +ok?+ to branch.
+    PasteString = Struct.new(:host, :token, :error, keyword_init: true) do
+      def ok?
+        error.nil?
+      end
+    end
+    private_constant :PasteString
+
+    # Result of +fetch_remote_env_file+: a successful +body+ (the env-file
+    # Ruby source) or a classified +error+ message. Use +ok?+ to branch.
+    FetchResult = Struct.new(:body, :error, keyword_init: true) do
+      def ok?
+        error.nil?
+      end
+    end
+    private_constant :FetchResult
+
+    # Split +<host>#<token>+ on the FIRST +#+ and validate the token shape and
+    # host scheme. The token is a URL fragment per the server contract (phase
+    # 7a), so everything after the first +#+ is the token regardless of any +#+
+    # it may contain (it never does for a +yrt_+ token, but splitting on the
+    # first delimiter is the robust choice). Returns a PasteString; never
+    # raises. Never echoes the token in the returned error.
+    #
+    # The host MUST use +https://+ — an +http://+ host would send the bootstrap
+    # Bearer token in cleartext over the wire. +http://+ is allowed only for
+    # loopback (local dev servers).
+    #
+    # @param input [String] the pasted bootstrap string
+    # @return [PasteString] parsed +host+/+token+ or a friendly +error+
+    def self.parse_paste_string(input)
+      input = input.to_s.strip
+
+      unless input.include?("#")
+        return malformed
+      end
+
+      host, token = input.split("#", 2)
+      host = host.to_s.strip
+      token = token.to_s.strip
+
+      return malformed if host.empty? || !token.match?(TOKEN_PATTERN)
+      return insecure_host unless secure_host?(host)
+
+      PasteString.new(host: host, token: token)
+    end
+
+    # Fetch the env file from the bootstrap endpoint, returning a FetchResult.
+    # On 200 the +body+ is the env-file Ruby source (served as +text/x-ruby+);
+    # non-2xx, network, and invalid-body responses are classified into friendly
+    # +error+ messages. Never echoes the token.
+    #
+    # Single-purpose invariant (spec §2.3): the token is sent ONLY to
+    # +<host>/api/v1/bootstrap/env_file+ as a Bearer credential. It is not
+    # written anywhere, not exported into the runtime environment, and not
+    # reused for any other API call. The served env file carries the EXISTING
+    # per-agent +mcp_api_key+s unchanged — those remain the runtime +X-API-Key+
+    # credential. This method is the ONLY site that handles the raw token.
+    #
+    # The fetched body is validated to be non-empty Ruby that evaluates to a
+    # Hash BEFORE it is treated as a success, so a transient empty/HTML/malformed
+    # response is reported cleanly instead of crashing +Config.load+'s
+    # downstream +eval+ (same trust boundary: the token-authenticated yatfa
+    # server, which +Config.load+ evals anyway).
+    #
+    # @param host [String] yatfa base URL (e.g. +https://app.yatfa.com+)
+    # @param token [String] raw +yrt_++64-hex bootstrap token
+    # @return [FetchResult] +body+ on success, classified +error+ otherwise
+    def self.fetch_remote_env_file(host:, token:)
+      url = "#{normalize_host(host)}#{ENV_FILE_PATH}"
+      body = YatfaAgent::HTTP.get_raw(url, headers: { "Authorization" => "Bearer #{token}" })
+      unless valid_env_file_body?(body)
+        return FetchResult.new(error: invalid_body_error)
+      end
+      FetchResult.new(body: body)
+    rescue YatfaAgent::HTTP::Error => e
+      FetchResult.new(error: classify_http_error(e.status_code, host))
+    rescue StandardError => e
+      # Network/DNS/timeout/socket — the server was unreachable. Do not echo
+      # the token; surface only the host and the generic failure cause.
+      FetchResult.new(error: "❌ Could not reach #{normalize_host(host)}: #{e.message}")
+    end
+
+    # Read the cached {host, token} pair, or nil if no cache exists / is
+    # unreadable. Returns a +[host, token]+ Array for ergonomic destructuring.
+    # @return [Array(String, String), nil]
+    def self.read_cached_credentials
+      return nil unless File.exist?(cache_file)
+
+      parsed =
+        begin
+          JSON.parse(File.read(cache_file))
+        rescue StandardError
+          nil
+        end
+
+      return nil unless parsed.is_a?(Hash)
+
+      host = parsed["host"].to_s
+      token = parsed["token"].to_s
+      return nil if host.empty? || !token.match?(TOKEN_PATTERN)
+
+      [host, token]
+    end
+
+    # Persist the {host, token} pair under +~/.yatfa/runner_bootstrap.json+
+    # with 0600 perms — created restrictive in ONE call (File.open + chmod
+    # would leave a world-readable window under umask 022; this cache holds the
+    # raw bootstrap token). Best effort — a cache write failure must not abort
+    # an otherwise-successful bootstrap, so it is logged and swallowed.
+    # @param host [String]
+    # @param token [String]
+    # @return [Boolean] true if written, false on failure
+    def self.write_cached_credentials(host:, token:)
+      FileUtils.mkdir_p(cache_dir)
+      File.open(cache_file, "w", 0o600) { |f| f.write(JSON.generate("host" => host, "token" => token)) }
+      true
+    rescue StandardError => e
+      puts "⚠️  Could not cache bootstrap token (#{e.message}); you'll need to paste again next time."
+      false
+    end
+
+    # Remove a stale/dead cache (e.g. after a cached fetch returns 401/404 so
+    # the next run re-prompts instead of looping on a revoked token). Logs a
+    # warning if the delete fails — a stuck cache means every subsequent run
+    # repeats a doomed fetch, which is worth surfacing (unlike a read failure,
+    # which is benignly treated as "no cache").
+    # @return [void]
+    def self.clear_cached_credentials
+      File.delete(cache_file) if File.exist?(cache_file)
+    rescue StandardError => e
+      puts "⚠️  Could not remove stale bootstrap cache (#{e.message}); it will be retried next run."
+    end
+
+    # Orchestrator: obtain +yatfa.env.rb+ for a fresh checkout via the
+    # bootstrap token path. Writes the file to +Dir.pwd+ on success (so the
+    # caller's subsequent +File.read+ finds it) and caches the credential for
+    # future checkouts. Exits 1 with guidance on any failure, or when no
+    # credential is obtainable non-interactively (CI/scripts).
+    #
+    # Precedence: a local +yatfa.env.rb+ ALWAYS wins — this method is only
+    # reached from +Config.load+ when that file is absent and the caller opted
+    # into the remote-fetch path via +allow_remote_fetch:+.
+    #
+    # @return [true] on success (file written)
+    # @raise [SystemExit] (+exit 1+) on failure or non-interactive-no-cache
+    def self.bootstrap_env_file!
+      # 1. Try a cached credential first (prior paste in another checkout).
+      if (creds = read_cached_credentials)
+        host, token = creds
+        result = fetch_remote_env_file(host: host, token: token)
+        if result.ok?
+          return true if write_env_file(result.body)
+
+          exit 1 # write_env_file already printed the cause
+        end
+
+        # Cached credential no longer works (revoked / server rotated keys).
+        # Clear it so we don't keep retrying a dead token, then fall through.
+        puts result.error
+        clear_cached_credentials
+      end
+
+      # 2. Non-interactive + no working cache → cannot prompt a tty that
+      # isn't there. Mirror the existing --no-prompt contract: exit, don't
+      # hang. Show the manual-setup template too, so a CI box with no token
+      # still has the actionable copy-paste fallback it had before this path.
+      if non_interactive?
+        puts ""
+        puts "❌ yatfa.env.rb not found and no bootstrap token cached."
+        puts "   Run 'npx yatfa setup' interactively once, paste a runner"
+        puts "   bootstrap token on a tty, OR create yatfa.env.rb manually:"
+        puts ""
+        puts YatfaAgent::Bootstrap.manual_setup_instructions
+        exit 1
+      end
+
+      # 3. Interactive: prompt ONCE for the paste string.
+      puts ""
+      puts "🔧 No yatfa.env.rb found in this checkout."
+      puts "   Paste a runner bootstrap string to fetch it"
+      puts "   (Project Settings → Runner token):"
+      print "> "
+      input = $stdin.gets&.strip.to_s
+
+      parsed = parse_paste_string(input)
+      unless parsed.ok?
+        puts parsed.error
+        exit 1
+      end
+
+      result = fetch_remote_env_file(host: parsed.host, token: parsed.token)
+      unless result.ok?
+        puts result.error
+        exit 1
+      end
+
+      exit 1 unless write_env_file(result.body)
+      write_cached_credentials(host: parsed.host, token: parsed.token)
+      true
+    end
+
+    # Write the fetched env-file content to +Dir.pwd/yatfa.env.rb+ — the same
+    # location the setup wizard writes to, so the downstream +Config.load+
+    # eval path (config.rb) is unchanged. Created 0600 (the file embeds agent
+    # +mcp_api_key+s and +dot_env+ secrets). Returns the path on success, nil
+    # (after printing a clean message) if the write itself fails — a rare but
+    # fatal condition (read-only cwd, ENOSPC) the caller cannot recover from.
+    # @param content [String] env-file Ruby source
+    # @return [String, nil] the path written, or nil on write failure
+    def self.write_env_file(content)
+      config_file = File.join(Dir.pwd, "yatfa.env.rb")
+      File.open(config_file, "w", 0o600) { |f| f.write(content) }
+      puts "✅ Wrote yatfa.env.rb from bootstrap token (#{config_file})"
+      puts "   Reminder: ensure it's gitignored  →  echo 'yatfa.env.rb' >> .gitignore"
+      config_file
+    rescue StandardError => e
+      puts "❌ Could not write #{config_file}: #{e.message}"
+      puts "   Fix the directory permissions/disk and re-run."
+      nil
+    end
+
+    # The manual-setup guidance shown when +yatfa.env.rb+ is missing and the
+    # bootstrap path can't produce one (no tty, no cached token — e.g. CI).
+    # Returned as a string so both this module's non-interactive branch and
+    # +Config.load+'s local-only missing-file branch can +puts+ the SAME
+    # actionable template (Config delegates here). Lives in Bootstrap rather
+    # than Config because +config.rb+ requires +bootstrap.rb+ (one-way), so the
+    # shared helper belongs in the lower layer to avoid a back-reference.
+    # @return [String]
+    def self.manual_setup_instructions
+      <<~MSG
+        ❌ Error: yatfa.env.rb not found in current directory
+
+        Create yatfa.env.rb:
+          {
+            yatfa_url: 'https://yatfa.example.com',  # Required
+            # ...
+            # Paste your stripped .env content here:
+            dot_env: <<~ENV
+              STRIPE_KEY=sk_test_...
+              OPENAI_KEY=sk-...
+            ENV
+          }
+          echo 'yatfa.env.rb' >> .gitignore
+      MSG
+    end
+
+    # Whether prompting is impossible/forbidden. Mirrors Interaction#non_interactive?
+    # (interaction.rb) — duplicated here so the Bootstrap module stays
+    # self-contained (no load-order/coupling dependency on Agent extending
+    # Interaction). Kept in sync with that definition by contract.
+    # @return [Boolean]
+    def self.non_interactive?
+      !$stdin.tty? || ENV["YATFA_NO_PROMPT"] == "1" || ARGV.include?("--no-prompt") || ARGV.include?("-d")
+    end
+
+    # True if +host+ may safely carry the bootstrap token: +https://+ always,
+    # or +http://+ only for loopback (local dev servers where TLS is unusual).
+    def self.secure_host?(host)
+      h = host.to_s.strip.downcase
+      return true if h.start_with?("https://")
+      return true if h.start_with?("http://localhost") ||
+                     h.start_with?("http://127.0.0.1") ||
+                     h.start_with?("http://0.0.0.0") ||
+                     h.start_with?("http://[::1]")
+
+      false
+    end
+    private_class_method :secure_host?
+
+    # A fetched env file is valid only if it is non-empty Ruby that evaluates
+    # to a Hash (the shape +Config.load+ expects). Guards against an empty /
+    # HTML / truncated server response being written to disk and then crashing
+    # the downstream +eval+.
+    def self.valid_env_file_body?(content)
+      return false if content.nil? || content.to_s.strip.empty?
+
+      eval(content).is_a?(Hash)
+    rescue StandardError, ScriptError
+      # ScriptError covers SyntaxError (malformed Ruby / HTML page); this is a
+      # validation predicate and must NEVER raise — any eval failure means the
+      # body is not a valid Hash literal, so report it as invalid.
+      false
+    end
+    private_class_method :valid_env_file_body?
+
+    # Classify a non-2xx status code into friendly, token-free guidance.
+    # Status semantics mirror the server contract (bootstrap_controller.rb):
+    # 401 = missing/malformed/revoked, 404 = well-formed but unknown.
+    def self.classify_http_error(status_code, host)
+      case status_code
+      when 401
+        "❌ Token invalid or revoked — generate a new bootstrap string in Project Settings → Runner token."
+      when 404
+        "❌ Token not recognized by this server — generate a new bootstrap string."
+      else
+        "❌ Server at #{normalize_host(host)} returned HTTP #{status_code} — try again or generate a new bootstrap string."
+      end
+    end
+    private_class_method :classify_http_error
+
+    # Strip trailing slashes from the host so +<host>+/api/v1/... is well-formed
+    # regardless of whether the pasted host ended in +/+. NOTE: the bootstrap
+    # host comes from the operator's paste string (the server that ISSUED the
+    # token), so it is intentionally NOT routed through YatfaAgent::UrlHelper —
+    # an explicit +YATFA_API_URL+ override must NOT redirect the token to a
+    # different server than the one that minted it (that would both fail auth
+    # and leak the credential).
+    def self.normalize_host(host)
+      host.to_s.sub(%r{/+\z}, "")
+    end
+    private_class_method :normalize_host
+
+    # The friendly "doesn't look like a bootstrap string" error. Centralized so
+    # the wording is identical for every malformed-input path. Never echoes input.
+    def self.malformed
+      PasteString.new(
+        error: "❌ That doesn't look like a runner bootstrap string — " \
+               "generate one from Project Settings → Runner token."
+      )
+    end
+    private_class_method :malformed
+
+    # The "host must use https" error (cleartext http would leak the token).
+    def self.insecure_host
+      PasteString.new(
+        error: "❌ Bootstrap host must use https:// (an http:// host would " \
+               "send the token in cleartext). Re-copy the full bootstrap " \
+               "string from Project Settings → Runner token."
+      )
+    end
+    private_class_method :insecure_host
+
+    def self.invalid_body_error
+      "❌ Server returned an invalid or empty env file. " \
+        "Try again, or generate a new bootstrap string."
+    end
+    private_class_method :invalid_body_error
+  end
+end

package/lib/yatfa_agent/config.rb

@@ -3,6 +3,7 @@
 require "json"
 require "digest"
 require_relative "http"
+require_relative "bootstrap"
 # Single source of truth for URL→{api,ws} derivation + the hosted default.
 # Loaded here (not duplicated) so the host-side launcher routes ALL URL
 # derivation through YatfaAgent::UrlHelper — the same module the in-container
@@ -31,24 +32,38 @@ module YatfaAgent
       nil
     end
 
-    def self.load
+    # Load +yatfa.env.rb+ from the current directory and normalize it.
+    #
+    # When the file is absent and +allow_remote_fetch+ is true (the runner
+    # entry point opts in), the bootstrap token path runs first: it fetches the
+    # env file from the server via a single-purpose runner token (see
+    # YatfaAgent::Bootstrap) and writes it to +Dir.pwd+, then this method
+    # loads it as if it had been there all along. A LOCAL +yatfa.env.rb+
+    # always wins — the remote-fetch path only runs when one is missing.
+    #
+    # When +allow_remote_fetch+ is false (the default — tests, CI, library
+    # callers), +Config.load+ stays a pure local-file reader: a missing file
+    # prints the manual-setup guidance and exits 1, exactly as before.
+    #
+    # @param allow_remote_fetch [Boolean] enable the bootstrap token path on a
+    #   missing file (default: false, keeps callers deterministic)
+    def self.load(allow_remote_fetch: false)
       config_file = File.join(Dir.pwd, "yatfa.env.rb")
 
       unless File.exist?(config_file)
-        puts "❌ Error: yatfa.env.rb not found in current directory"
-        puts ""
-        puts "Create yatfa.env.rb:"
-        puts "  {"
-        puts "    yatfa_url: 'https://yatfa.example.com',  # Required"
-        puts "    # ..."
-        puts "    # Paste your stripped .env content here:"
-        puts "    dot_env: <<~ENV"
-        puts "      STRIPE_KEY=sk_test_..."
-        puts "      OPENAI_KEY=sk-..."
-        puts "    ENV"
-        puts "  }"
-        puts "  echo 'yatfa.env.rb' >> .gitignore"
-        exit 1
+        if allow_remote_fetch
+          # Fetches +yatfa.env.rb+ via a single-purpose bootstrap token and
+          # writes it to Dir.pwd, or exits 1 with guidance. On success the
+          # file now exists and the eval path below loads it unchanged.
+          # Local>token>error precedence holds: we only reach here when no
+          # local file is present.
+          YatfaAgent::Bootstrap.bootstrap_env_file!
+        else
+          # Shared with the bootstrap non-interactive path so both surfaces
+          # print the same actionable template.
+          puts YatfaAgent::Bootstrap.manual_setup_instructions
+          exit 1
+        end
       end
 
       puts "⚙️  Loading configuration from yatfa.env.rb"

package/lib/yatfa_agent/http.rb

@@ -43,6 +43,30 @@ module YatfaAgent
       handle_response(response)
     end
 
+    # Perform a GET request returning the RAW response body as a String on
+    # success (NO JSON parsing). Use this for endpoints that serve non-JSON
+    # bodies — e.g. the bootstrap env-file endpoint serves +text/x-ruby+
+    # (Ruby source), which would raise JSON::ParserError under +.get+.
+    #
+    # Raises YatfaAgent::HTTP::Error (with +status_code+) for non-2xx exactly
+    # like +.get+, so callers can reuse the +rescue HTTP::Error => e;
+    # case e.status_code+ classification pattern unchanged.
+    #
+    # @param url [String] full URL to request
+    # @param headers [Hash] HTTP headers (e.g. { "Authorization" => "Bearer x" })
+    # @param open_timeout [Integer] connection timeout in seconds (default: 5)
+    # @param read_timeout [Integer] response timeout in seconds (default: 10)
+    # @return [String] raw response body
+    # @raise [Error] for non-2xx HTTP responses
+    def self.get_raw(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, raw: true)
+    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.
@@ -81,9 +105,14 @@ module YatfaAgent
         JSON.parse(body)
       end
 
-      def handle_response(response)
+      # Parse a 2xx success body. By default the body is parsed as JSON (the
+      # contract every existing caller relies on); pass +raw: true+ to return
+      # the body verbatim — for non-JSON endpoints (e.g. the bootstrap env-file
+      # endpoint serves +text/x-ruby+). The non-2xx error path is shared so the
+      # +Error+ shape (with +status_code+) is identical either way.
+      def handle_response(response, raw: false)
         if response.is_a?(Net::HTTPSuccess)
-          parse_json(response.body)
+          raw ? response.body : parse_json(response.body)
         else
           raise Error.new(
             "HTTP #{response.code} #{response.message}",

package/package.json

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

package/setup/http_client.rb

@@ -43,6 +43,30 @@ module YatfaAgent
       handle_response(response)
     end
 
+    # Perform a GET request returning the RAW response body as a String on
+    # success (NO JSON parsing). Use this for endpoints that serve non-JSON
+    # bodies — e.g. the bootstrap env-file endpoint serves +text/x-ruby+
+    # (Ruby source), which would raise JSON::ParserError under +.get+.
+    #
+    # Raises YatfaAgent::HTTP::Error (with +status_code+) for non-2xx exactly
+    # like +.get+, so callers can reuse the +rescue HTTP::Error => e;
+    # case e.status_code+ classification pattern unchanged.
+    #
+    # @param url [String] full URL to request
+    # @param headers [Hash] HTTP headers (e.g. { "Authorization" => "Bearer x" })
+    # @param open_timeout [Integer] connection timeout in seconds (default: 5)
+    # @param read_timeout [Integer] response timeout in seconds (default: 10)
+    # @return [String] raw response body
+    # @raise [Error] for non-2xx HTTP responses
+    def self.get_raw(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, raw: true)
+    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.
@@ -81,9 +105,14 @@ module YatfaAgent
         JSON.parse(body)
       end
 
-      def handle_response(response)
+      # Parse a 2xx success body. By default the body is parsed as JSON (the
+      # contract every existing caller relies on); pass +raw: true+ to return
+      # the body verbatim — for non-JSON endpoints (e.g. the bootstrap env-file
+      # endpoint serves +text/x-ruby+). The non-2xx error path is shared so the
+      # +Error+ shape (with +status_code+) is identical either way.
+      def handle_response(response, raw: false)
         if response.is_a?(Net::HTTPSuccess)
-          parse_json(response.body)
+          raw ? response.body : parse_json(response.body)
         else
           raise Error.new(
             "HTTP #{response.code} #{response.message}",