openclacky 0.9.11 → 0.9.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5db22957073a294578efa60af05e69277891f976bb24d6d9397d5abbefeaf6b8
-  data.tar.gz: 3103ec5cf881eb0ebe16f79a5f136c01ef890255ebeda9757d4aa5f592071470
+  metadata.gz: 791fa59b1013c559e294b373e1a7ba671545eef76ae7037ed3c604ed9f269b45
+  data.tar.gz: 8ffae20491125d886e36387b811f9ea8c2e2fcc76d76d10e08224bcc06a93972
 SHA512:
-  metadata.gz: 55fe30f89017da76ac2a9348fea1a1f4d701006d4c882878e09e915600ac80dcf72131d546b7e786c3588c1c848e47db4628478ce018e619a2d7781bd0cdbfe3
-  data.tar.gz: a6923ec51d5a5d60c2a5bd07b7fa269a76087456ea5adf4d7b33a9dc1c8a43f043570a6d4c6f6309b24dc2ad60850dd4d993cc9444fd22c76445e3749952ca09
+  metadata.gz: 6895348aeef5d8ed713273a2d386e390a018e5b4991c37a7fd20b7fdbb4782fc945779b45556f31cb2a0894f78df72efc80ad4661b3b95d89cd8ab0c333b65a0
+  data.tar.gz: 01c35bb0a3377b81c4e3f89892d58b10472f9611347ed9b0478872e76e3c236def6b499475df32d6020c56fe94dcd33c11495512ee94a5a44a1c81aefbaaad3e

data/CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.9.12] - 2026-03-27
+
+### Added
+- **Improved Anthropic prompt cache hit rate (2-point caching)**: the last 2 eligible messages are now marked for caching instead of 1, so Turn N's cached prefix is still a hit in Turn N+1 — significantly reducing API costs for long sessions
+
+### Improved
+- **Ruby 2.6+ and macOS system Ruby compatibility**: the gem now works with the macOS built-in Ruby (2.6) and LibreSSL — includes polyfills for `filter_map`, `File.absolute_path?`, `URI.encode_uri_component`, and a pure-Ruby AES-256-GCM fallback for LibreSSL environments where native OpenSSL GCM is unavailable
+- **Install script streamlined for China**: the installer is now significantly simplified and more reliable for users in China — direct Alibaba Cloud mirror for RubyGems, plus a dedicated CN-optimized install path
+- **Compression no longer crashes when system prompt is frozen**: fixed a bug where message compression would raise `FrozenError` by mutating the shared system prompt object — it now safely duplicates the string before modification
+
+### Fixed
+- **Compression crash on frozen system prompt**: `MessageCompressor` now calls `.dup` on the system prompt before injecting the compression instruction, preventing `FrozenError` in long sessions
+
 ## [0.9.11] - 2026-03-25
 
 ### Added

data/docs/install-script-simplification.md

@@ -0,0 +1,89 @@
+# Install Script Simplification Plan
+
+## Background
+
+We now support Ruby >= 2.6.0 (down from 3.1.0). This opens the door to significantly
+simplifying the install script by leveraging the system Ruby that ships with older macOS versions.
+
+## Current Flow (Heavy)
+
+```
+install.sh
+  → detect_network_region
+  → install_macos_dependencies
+      → Homebrew (+ openssl@3, libyaml, gmp build deps)
+      → mise (Ruby version manager)
+      → Ruby 3 (via mise)
+      → Node 22 (via mise, for chrome-devtools-mcp)
+  → gem install openclacky
+  → install_chrome_devtools_mcp (npm install -g)
+```
+
+## Target Flow (Simplified)
+
+```
+check_ruby >= 2.6?
+  ├── YES → gem install openclacky ✅  (done, zero extra deps)
+  └── NO  → check CLT exists (xcode-select -p)
+              ├── YES → mise install ruby → gem install ✅
+              └── NO  → print clear instructions, exit:
+                          Option 1: xcode-select --install  (then re-run installer)
+                          Option 2: brew install ruby        (if brew already exists)
+```
+
+## Key Decisions
+
+### Ruby version threshold: 3.1 → 2.6
+- macOS 10.15 Catalina: Ruby 2.6.3 ✅
+- macOS 11 Big Sur: Ruby 2.6.8 ✅
+- macOS 12+ Monterey and above: no system Ruby (Apple removed it)
+
+### Homebrew: removed from happy path
+- Only Homebrew's build deps (openssl@3, libyaml, gmp) were needed to compile Ruby via mise
+- If system Ruby exists, none of these are needed
+- Homebrew itself is NOT installed by the script anymore
+
+### mise: fallback only
+- Only invoked when system Ruby is absent (macOS 12+)
+- Requires Xcode CLT to be present first (for compiling Ruby)
+- No longer used to install Node
+
+### Node / chrome-devtools-mcp: removed from install.sh
+- Browser automation is an optional feature
+- Move Node installation guidance into the `browser-setup` skill
+- `clacky browser setup` handles Node + chrome-devtools-mcp installation
+
+## Xcode CLT Handling (Deferred)
+
+Brew uses a clever trick to install CLT silently (no GUI popup):
+
+```bash
+# Creates a placeholder file that triggers softwareupdate to list CLT
+touch /tmp/.com.apple.dt.CommandLineTools.installondemand.in-progress
+
+# Find the CLT package label
+clt_label=$(softwareupdate -l | grep "Command Line Tools" | ...)
+
+# Silent install — no GUI!
+sudo softwareupdate -i "${clt_label}"
+```
+
+However this still requires `sudo` (root password). Given that:
+- macOS 12+ users who lack CLT are rare (any git/Xcode/Homebrew usage installs it)
+- Silent CLT install downloads hundreds of MB
+
+The current plan is to **not auto-install CLT**, and instead print clear instructions
+asking the user to run `xcode-select --install` and re-run the installer.
+
+We can revisit adopting Homebrew's `softwareupdate` approach in the future if
+the "no CLT" case proves common enough.
+
+## Files to Change
+
+| File | Change |
+|------|--------|
+| `scripts/install.sh` | Ruby threshold 3.1 → 2.6; remove Homebrew install; remove Node/npm install; simplify macOS deps function |
+| `README.md` | Ruby badge and requirements: >= 3.1.0 → >= 2.6.0 |
+| `docs/HOW-TO-USE.md` | Requirements: Ruby >= 3.1 → >= 2.6 |
+| `docs/HOW-TO-USE-CN.md` | Same as above |
+| `homebrew/openclacky.rb` | `depends_on "ruby@3.3"` → remove or update |

data/lib/clacky/aes_gcm.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "base64"
+
+module Clacky
+  # Pure-Ruby AES-256-GCM implementation.
+  #
+  # Why this exists:
+  #   macOS ships Ruby 2.6 linked against LibreSSL 3.3.x which has a known
+  #   bug: AES-GCM encrypt/decrypt raises CipherError even for valid inputs.
+  #   This implementation uses AES-256-ECB (which LibreSSL supports correctly)
+  #   as the single block-cipher primitive and builds GCM on top:
+  #
+  #     - CTR mode   → keystream for encryption / decryption
+  #     - GHASH      → authentication tag
+  #
+  # The output is 100% compatible with OpenSSL / standard AES-256-GCM:
+  #   ciphertext, iv, and auth_tag produced here can be decrypted by OpenSSL
+  #   and vice-versa.
+  #
+  # Reference: NIST SP 800-38D
+  #
+  # Usage:
+  #   ct, tag = AesGcm.encrypt(key, iv, plaintext, aad)
+  #   pt      = AesGcm.decrypt(key, iv, ciphertext, tag, aad)
+  module AesGcm
+    BLOCK_SIZE = 16
+    TAG_LENGTH = 16
+
+    # Encrypt plaintext with AES-256-GCM.
+    #
+    # @param key        [String] 32-byte binary key
+    # @param iv         [String] 12-byte binary IV (recommended for GCM)
+    # @param plaintext  [String] binary or UTF-8 plaintext
+    # @param aad        [String] additional authenticated data (may be empty)
+    # @return [Array<String, String>] [ciphertext, auth_tag] both binary strings
+    def self.encrypt(key, iv, plaintext, aad = "")
+      aes  = aes_ecb(key)
+      h    = aes.call("\x00" * BLOCK_SIZE)              # H = E(K, 0^128)
+      j0   = build_j0(iv, h)
+      ct   = ctr_crypt(aes, inc32(j0), plaintext.b)
+      tag  = compute_tag(aes, h, j0, ct, aad.b)
+      [ct, tag]
+    end
+
+    # Decrypt ciphertext with AES-256-GCM and verify auth tag.
+    #
+    # @param key        [String] 32-byte binary key
+    # @param iv         [String] 12-byte binary IV
+    # @param ciphertext [String] binary ciphertext
+    # @param tag        [String] 16-byte binary auth tag
+    # @param aad        [String] additional authenticated data (may be empty)
+    # @return [String] plaintext (UTF-8)
+    # @raise  [OpenSSL::Cipher::CipherError] on authentication failure
+    def self.decrypt(key, iv, ciphertext, tag, aad = "")
+      aes       = aes_ecb(key)
+      h         = aes.call("\x00" * BLOCK_SIZE)
+      j0        = build_j0(iv, h)
+      exp_tag   = compute_tag(aes, h, j0, ciphertext, aad.b)
+
+      unless secure_compare(exp_tag, tag)
+        raise OpenSSL::Cipher::CipherError, "bad decrypt (authentication tag mismatch)"
+      end
+
+      ctr_crypt(aes, inc32(j0), ciphertext).force_encoding("UTF-8")
+    end
+
+    # ── Private helpers ──────────────────────────────────────────────────────
+
+    # Return a lambda: block(16 bytes) → encrypted block(16 bytes)
+    private_class_method def self.aes_ecb(key)
+      lambda do |block|
+        c = OpenSSL::Cipher.new("aes-256-ecb")
+        c.encrypt
+        c.padding = 0
+        c.key     = key
+        c.update(block) + c.final
+      end
+    end
+
+    # Build J0 counter block.
+    # For 12-byte IVs (standard): J0 = IV || 0x00000001
+    # For other lengths: J0 = GHASH(H, {}, IV)
+    private_class_method def self.build_j0(iv, h)
+      if iv.bytesize == 12
+        iv.b + "\x00\x00\x00\x01"
+      else
+        ghash(h, "", iv.b)
+      end
+    end
+
+    # CTR-mode encryption/decryption (symmetric — same operation).
+    # Starting counter block is `ctr0` (already incremented to J0+1 by caller).
+    private_class_method def self.ctr_crypt(aes, ctr0, data)
+      return "".b if data.empty?
+
+      out = "".b
+      ctr = ctr0.dup
+      pos = 0
+
+      while pos < data.bytesize
+        keystream = aes.call(ctr)
+        chunk     = data.byteslice(pos, BLOCK_SIZE)
+        out << xor_blocks(keystream, chunk)
+        ctr = inc32(ctr)
+        pos += BLOCK_SIZE
+      end
+
+      out
+    end
+
+    # Compute GCM auth tag.
+    # tag = E(K, J0) XOR GHASH(H, aad, ciphertext)
+    private_class_method def self.compute_tag(aes, h, j0, ciphertext, aad)
+      s   = ghash(h, aad, ciphertext)
+      ej0 = aes.call(j0)
+      xor_blocks(ej0, s)
+    end
+
+    # GHASH: polynomial hashing over GF(2^128)
+    # ghash = Σ (Xi * H^i) where Xi are 128-bit blocks of padded aad + ciphertext + lengths
+    private_class_method def self.ghash(h, aad, ciphertext)
+      h_int = bytes_to_int(h)
+      x     = 0
+
+      # Process AAD blocks
+      each_block(aad) { |blk| x = gf128_mul(bytes_to_int(blk) ^ x, h_int) }
+
+      # Process ciphertext blocks
+      each_block(ciphertext) { |blk| x = gf128_mul(bytes_to_int(blk) ^ x, h_int) }
+
+      # Final block: len(aad) || len(ciphertext) in bits, each as 64-bit big-endian
+      len_block = [aad.bytesize * 8].pack("Q>") + [ciphertext.bytesize * 8].pack("Q>")
+      x = gf128_mul(bytes_to_int(len_block) ^ x, h_int)
+
+      int_to_bytes(x)
+    end
+
+    # Iterate over 16-byte zero-padded blocks of data, yielding each block.
+    private_class_method def self.each_block(data, &block)
+      return if data.empty?
+
+      i = 0
+      while i < data.bytesize
+        chunk = data.byteslice(i, BLOCK_SIZE)
+        chunk = chunk.ljust(BLOCK_SIZE, "\x00") if chunk.bytesize < BLOCK_SIZE
+        block.call(chunk)
+        i += BLOCK_SIZE
+      end
+    end
+
+    # Galois Field GF(2^128) multiplication.
+    # Reduction polynomial: x^128 + x^7 + x^2 + x + 1
+    # Uses the reflected bit order per GCM spec.
+    R = 0xe1000000000000000000000000000000
+    private_class_method def self.gf128_mul(x, y)
+      z = 0
+      v = x
+      128.times do
+        z ^= v if y & (1 << 127) != 0
+        lsb = v & 1
+        v >>= 1
+        v ^= R if lsb == 1
+        y <<= 1
+        y &= (1 << 128) - 1
+      end
+      z
+    end
+
+    # Increment the rightmost 32 bits of a 16-byte counter block (big-endian).
+    private_class_method def self.inc32(block)
+      prefix  = block.byteslice(0, 12)
+      counter = block.byteslice(12, 4).unpack1("N")
+      prefix + [(counter + 1) & 0xFFFFFFFF].pack("N")
+    end
+
+    # XOR two binary strings, truncated to the shorter length.
+    private_class_method def self.xor_blocks(a, b)
+      len = [a.bytesize, b.bytesize].min
+      len.times.map { |i| (a.getbyte(i) ^ b.getbyte(i)).chr }.join.b
+    end
+
+    # Convert a binary string to an unsigned big-endian integer.
+    private_class_method def self.bytes_to_int(str)
+      str.bytes.inject(0) { |acc, b| (acc << 8) | b }
+    end
+
+    # Convert an unsigned integer to a 16-byte big-endian binary string.
+    private_class_method def self.int_to_bytes(n)
+      bytes = []
+      16.times { bytes.unshift(n & 0xFF); n >>= 8 }
+      bytes.pack("C*")
+    end
+
+    # Constant-time string comparison to prevent timing attacks.
+    private_class_method def self.secure_compare(a, b)
+      return false if a.bytesize != b.bytesize
+
+      result = 0
+      a.bytes.zip(b.bytes) { |x, y| result |= x ^ y }
+      result == 0
+    end
+  end
+end

data/lib/clacky/agent/message_compressor.rb

@@ -99,8 +99,13 @@ module Clacky
         raise "LLM compression failed: unable to parse compressed messages"
       end
 
-      # Return system message + compressed messages + recent messages
-      [system_msg, *parsed_messages, *recent_messages].compact
+      # Return system message + compressed messages + recent messages.
+      # Strip any system messages from recent_messages as a safety net —
+      # get_recent_messages_with_tool_pairs already excludes them, but this
+      # guard ensures we never end up with duplicate system prompts even if
+      # the caller passes an unfiltered list.
+      safe_recent = recent_messages.reject { |m| m[:role] == "system" }
+      [system_msg, *parsed_messages, *safe_recent].compact
     end
 
     private

data/lib/clacky/agent/message_compressor_helper.rb

@@ -135,6 +135,14 @@ module Clacky
           chunk_path: chunk_path
         ))
 
+        # Reset to the estimated size of the rebuilt (small) history.
+        # The compression call_llm reported the OLD large token count, so
+        # @previous_total_tokens would still be above COMPRESSION_THRESHOLD —
+        # without this reset the very next think() would re-trigger compression
+        # immediately, causing an infinite loop (especially after image uploads
+        # where base64 data inflates token counts dramatically).
+        @previous_total_tokens = @history.estimate_tokens
+
         # Track this compression
         @compressed_summaries << {
           level: compression_context[:compression_level],
@@ -167,6 +175,14 @@ module Clacky
         while i >= 0 && messages_collected < count
           msg = messages[i]
 
+          # Never include the system message — it is always prepended separately
+          # by rebuild_with_compression. Including it here would cause it to appear
+          # twice in the rebuilt history, inflating token counts on every compression.
+          if msg[:role] == "system"
+            i -= 1
+            next
+          end
+
           if messages_to_include.include?(i)
             i -= 1
             next

data/lib/clacky/agent.rb

@@ -38,7 +38,9 @@ module Clacky
                 :cache_stats, :cost_source, :ui, :skill_loader, :agent_profile,
                 :status, :error, :updated_at, :source
 
-    def permission_mode = @config&.permission_mode&.to_s || ""
+    def permission_mode
+      @config&.permission_mode&.to_s || ""
+    end
 
     def initialize(client, config, working_dir:, ui:, profile:, session_id:, source:)
       @client = client  # Client for current model

data/lib/clacky/brand_config.rb

@@ -1070,11 +1070,24 @@ module Clacky
     # @raise [RuntimeError] on decryption failure (wrong key, tampered data)
     private def aes_gcm_decrypt(key, ciphertext, iv_b64, tag_b64)
       require "base64"
-      cipher          = OpenSSL::Cipher.new("aes-256-gcm").decrypt
-      cipher.key      = key
-      cipher.iv       = Base64.strict_decode64(iv_b64)
-      cipher.auth_tag = Base64.strict_decode64(tag_b64)
-      (cipher.update(ciphertext) + cipher.final).force_encoding("UTF-8")
+      require_relative "aes_gcm"
+
+      iv  = Base64.strict_decode64(iv_b64)
+      tag = Base64.strict_decode64(tag_b64)
+
+      # Try native OpenSSL AES-GCM first (fastest path; works on real OpenSSL).
+      # LibreSSL 3.3.x has a known bug where AES-GCM raises CipherError even
+      # for valid inputs, so we fall back to the pure-Ruby implementation.
+      begin
+        cipher          = OpenSSL::Cipher.new("aes-256-gcm").decrypt
+        cipher.key      = key
+        cipher.iv       = iv
+        cipher.auth_tag = tag
+        (cipher.update(ciphertext) + cipher.final).force_encoding("UTF-8")
+      rescue OpenSSL::Cipher::CipherError
+        # Native GCM failed — use pure-Ruby fallback (LibreSSL-safe)
+        Clacky::AesGcm.decrypt(key, iv, ciphertext, tag)
+      end
     rescue OpenSSL::Cipher::CipherError => e
       raise "Decryption failed: #{e.message}. " \
             "The file may be corrupted or the license key is incorrect."

data/lib/clacky/client.rb

@@ -185,20 +185,31 @@ module Clacky
 
     # ── Prompt caching helpers ────────────────────────────────────────────────
 
-    # Add cache_control marker to the appropriate message in the array.
-    # Strategy: mark the last message, unless that message is a compression
-    # instruction (system_injected: true) — in that case mark the one before it.
+    # Add cache_control markers to the last 2 messages in the array.
+    #
+    # Why 2 markers:
+    #   Turn N   — marks messages[-2] and messages[-1]; server caches prefix up to [-1]
+    #   Turn N+1 — messages[-2] is Turn N's last message (still marked) → cache READ hit;
+    #              messages[-1] is the new message (marked) → cache WRITE for Turn N+2
+    #
+    # With only 1 marker (old behavior): Turn N marks messages[-1]; in Turn N+1 that same
+    # message is now [-2] and carries no marker → server sees a different prefix → cache MISS.
+    #
+    # Compression instructions (system_injected: true) are skipped — we never want to cache
+    # those ephemeral injection messages.
     def apply_message_caching(messages)
       return messages if messages.empty?
 
-      cache_index = if is_compression_instruction?(messages.last)
-                      [messages.length - 2, 0].max
-                    else
-                      messages.length - 1
-                    end
+      # Collect up to 2 candidate indices from the tail, skipping compression instructions.
+      candidate_indices = []
+      (messages.length - 1).downto(0) do |i|
+        break if candidate_indices.length >= 2
+
+        candidate_indices << i unless is_compression_instruction?(messages[i])
+      end
 
       messages.map.with_index do |msg, idx|
-        idx == cache_index ? add_cache_control_to_message(msg) : msg
+        candidate_indices.include?(idx) ? add_cache_control_to_message(msg) : msg
       end
     end
 

data/lib/clacky/default_skills/channel-setup/weixin_setup.rb

@@ -49,8 +49,8 @@ GIVEN_QRCODE_ID = QRCODE_ID_IDX ? ARGV[QRCODE_ID_IDX + 1] : nil
 # Logging (suppress in --fetch-qr mode so stdout is clean JSON)
 # ---------------------------------------------------------------------------
 
-def step(msg) = $stderr.puts("[weixin-setup] #{msg}") unless FETCH_QR_MODE
-def ok(msg)   = $stderr.puts("[weixin-setup] ✅ #{msg}") unless FETCH_QR_MODE
+def step(msg); $stderr.puts("[weixin-setup] #{msg}") unless FETCH_QR_MODE; end
+def ok(msg);   $stderr.puts("[weixin-setup] ✅ #{msg}") unless FETCH_QR_MODE; end
 
 # In fetch-qr mode, write to stderr so stdout stays clean JSON
 def log(msg)

data/lib/clacky/server/browser_manager.rb

@@ -194,7 +194,7 @@ module Clacky
 
     def load_config
       return {} unless File.exist?(BROWSER_CONFIG_PATH)
-      YAML.safe_load(File.read(BROWSER_CONFIG_PATH), permitted_classes: [Date, Time, Symbol]) || {}
+      YAMLCompat.safe_load(File.read(BROWSER_CONFIG_PATH), permitted_classes: [Date, Time, Symbol]) || {}
     rescue StandardError => e
       Clacky::Logger.warn("[BrowserManager] Failed to read browser.yml: #{e.message}")
       {}

data/lib/clacky/server/channel/adapters/weixin/api_client.rb

@@ -37,7 +37,10 @@ module Clacky
           # Raised for non-zero API return codes or HTTP errors.
           class ApiError < StandardError
             attr_reader :code
-            def initialize(code, msg) = (@code = code; super("WeixinApiError(#{code}): #{msg.to_s.slice(0, 200)}"))
+            def initialize(code, msg)
+              @code = code
+              super("WeixinApiError(#{code}): #{msg.to_s.slice(0, 200)}")
+            end
           end
 
           # Raised on network/read timeouts.

data/lib/clacky/server/channel/channel_config.rb

@@ -38,7 +38,7 @@ module Clacky
     # @return [ChannelConfig]
     def self.load(config_file = CONFIG_FILE)
       if File.exist?(config_file)
-        data = YAML.safe_load(File.read(config_file), permitted_classes: [Symbol]) || {}
+        data = YAMLCompat.safe_load(File.read(config_file), permitted_classes: [Symbol]) || {}
       else
         data = {}
       end

data/lib/clacky/server/http_server.rb

@@ -75,7 +75,7 @@ module Clacky
 
       # Ignore all other UI methods (progress, errors, etc.) during history replay
       def method_missing(name, *args, **kwargs); end
-      def respond_to_missing?(name, include_private = false) = true
+      def respond_to_missing?(name, include_private = false); true; end
     end
 
     # HttpServer runs an embedded WEBrick HTTP server with WebSocket support.

data/lib/clacky/server/scheduler.rb

@@ -244,7 +244,7 @@ module Clacky
       private def load_schedules
         return [] unless File.exist?(SCHEDULES_FILE)
 
-        data = YAML.load_file(SCHEDULES_FILE, permitted_classes: [Symbol])
+        data = YAMLCompat.load_file(SCHEDULES_FILE, permitted_classes: [Symbol])
         Array(data)
       rescue => e
         Clacky::Logger.error("scheduler_load_schedules_error", error: e)

data/lib/clacky/tools/browser.rb

@@ -234,7 +234,7 @@ module Clacky
       end
 
       private def browser_enabled?
-        config = YAML.safe_load(File.read(BROWSER_CONFIG_PATH), permitted_classes: [Date, Time, Symbol])
+        config = YAMLCompat.safe_load(File.read(BROWSER_CONFIG_PATH), permitted_classes: [Date, Time, Symbol])
         config.is_a?(Hash) && config["enabled"] == true
       end
 

data/lib/clacky/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Clacky
-  VERSION = "0.9.11"
+  VERSION = "0.9.12"
 end

data/lib/clacky.rb

@@ -1,5 +1,56 @@
 # frozen_string_literal: true
 
+# ── Ruby < 2.7 polyfills ──────────────────────────────────────────────────────
+
+# Enumerable#filter_map was added in Ruby 2.7.
+if RUBY_VERSION < "2.7"
+  module Enumerable
+    def filter_map(&block)
+      return to_enum(:filter_map) unless block
+
+      each_with_object([]) do |item, result|
+        mapped = block.call(item)
+        result << mapped if mapped
+      end
+    end
+  end
+end
+
+# File.absolute_path? was added in Ruby 2.7.
+# Polyfill: a path is absolute if it starts with "/" (Unix) or a drive letter (Windows).
+unless File.respond_to?(:absolute_path?)
+  def File.absolute_path?(path)
+    File.expand_path(path) == path.to_s
+  end
+end
+
+# URI.encode_uri_component was added in Ruby 3.2.
+# CGI.escape encodes spaces as '+'; replace with '%20' to match URI encoding.
+require "uri"
+require "cgi"
+unless URI.respond_to?(:encode_uri_component)
+  def URI.encode_uri_component(str)
+    CGI.escape(str.to_s).gsub("+", "%20")
+  end
+end
+
+# YAML.safe_load with permitted_classes: keyword was added in Psych 4 (Ruby 3.1).
+# On older Ruby, the second positional argument serves the same purpose.
+# This helper provides a unified interface across Ruby versions.
+module YAMLCompat
+  def self.safe_load(yaml_string, permitted_classes: [])
+    if Psych::VERSION >= "4.0"
+      YAML.safe_load(yaml_string, permitted_classes: permitted_classes)
+    else
+      YAML.safe_load(yaml_string, permitted_classes)
+    end
+  end
+
+  def self.load_file(path, permitted_classes: [])
+    safe_load(File.read(path), permitted_classes: permitted_classes)
+  end
+end
+
 require_relative "clacky/version"
 require_relative "clacky/message_format/anthropic"
 require_relative "clacky/message_format/open_ai"