openclacky 1.5.6 → 1.5.7

data/lib/clacky/mcp/http_transport.rb

@@ -23,12 +23,15 @@ module Clacky
       DEFAULT_OPEN_TIMEOUT = 10
       DEFAULT_READ_TIMEOUT = 120
 
-      def initialize(name:, url:, headers: {}, open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
+      def initialize(name:, url:, headers: {}, authorization: nil, requester: nil,
+                     open_timeout: DEFAULT_OPEN_TIMEOUT, read_timeout: DEFAULT_READ_TIMEOUT)
         @name = name
         @uri  = URI.parse(url)
         raise TransportError, "MCP server '#{name}' url is not http(s): #{url}" unless %w[http https].include?(@uri.scheme)
 
         @extra_headers = (headers || {}).transform_keys(&:to_s).transform_values(&:to_s)
+        @authorization = authorization
+        @requester = requester
         @open_timeout  = open_timeout
         @read_timeout  = read_timeout
 
@@ -79,21 +82,17 @@ module Clacky
         @last_error ? "last error: #{@last_error.class}: #{@last_error.message}" : ""
       end
 
-      private def dispatch_post(body, is_request:)
-        http = Net::HTTP.new(@uri.host, @uri.port)
-        http.use_ssl = (@uri.scheme == "https")
-        http.open_timeout = @open_timeout
-        http.read_timeout = @read_timeout
-
+      private def dispatch_post(body, is_request:, retried: false)
         req = Net::HTTP::Post.new(@uri.request_uri)
         req["Content-Type"] = "application/json"
         req["Accept"]       = "application/json, text/event-stream"
         req["MCP-Protocol-Version"] = Client::PROTOCOL_VERSION if defined?(Client::PROTOCOL_VERSION)
         @lock.synchronize { req["Mcp-Session-Id"] = @session_id if @session_id }
         @extra_headers.each { |k, v| req[k] = v }
+        @authorization&.authorization_headers&.each { |k, v| req[k] = v }
         req.body = body
 
-        http.request(req) do |res|
+        perform_request(req) do |res|
           if (sid = res["Mcp-Session-Id"])
             @lock.synchronize { @session_id = sid }
           end
@@ -102,9 +101,16 @@ module Clacky
           if status == 202
             return
           end
+          if status == 401 && @authorization && !retried
+            res.read_body.to_s
+            @authorization.invalidate!
+            return dispatch_post(body, is_request: is_request, retried: true)
+          end
           if status >= 400
             text = res.read_body.to_s
-            raise TransportError, "HTTP #{status} from MCP server '#{@name}': #{text[0, 500]}"
+            message = "HTTP #{status} from MCP server '#{@name}'"
+            message += ": #{text[0, 500]}" unless status == 401
+            raise TransportError, message
           end
 
           ctype = (res["Content-Type"] || "").downcase
@@ -123,6 +129,16 @@ module Clacky
         end
       end
 
+      private def perform_request(request, &block)
+        return @requester.call(request, &block) if @requester
+
+        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.request(request, &block)
+      end
+
       private def consume_sse(res)
         buffer = String.new
         res.read_body do |chunk|

data/lib/clacky/mcp/oauth/authorization_manager.rb

@@ -0,0 +1,257 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+require "net/http"
+require "securerandom"
+require "digest"
+require "base64"
+require "socket"
+require "timeout"
+
+module Clacky
+  module Mcp
+    module OAuth
+      class AuthorizationManager
+        Response = Struct.new(:status, :headers, :body)
+        MAX_RESPONSE_BYTES = 1_048_576
+
+        class Error < StandardError; end
+
+        def self.pkce_challenge(verifier)
+          Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
+        end
+
+        def initialize(server_name:, config:, store:, requester: nil, callback: nil, clock: nil)
+          @server_name = server_name
+          @config = config
+          @store = store
+          @requester = requester || method(:request)
+          @callback = callback
+          @clock = clock || -> { Time.now.to_i }
+        end
+
+        def login(resource_metadata_url: nil)
+          raise Error, "MCP server '#{@server_name}' is not configured for OAuth" unless @config.enabled?
+
+          receiver = @callback || CallbackReceiver.new
+          redirect_uri = receiver.respond_to?(:redirect_uri) ? receiver.redirect_uri : "http://127.0.0.1:52963/callback"
+          metadata = discover_metadata(resource_metadata_url)
+          client = register_client(metadata, redirect_uri)
+          verifier = SecureRandom.urlsafe_base64(48, false)
+          state = SecureRandom.urlsafe_base64(32, false)
+          authorization_url = build_authorization_url(metadata, client.fetch("client_id"), redirect_uri, verifier, state)
+          callback_result = receiver.call(authorization_url, state)
+          raise Error, "OAuth callback state mismatch" unless callback_result["state"].to_s == state
+          raise Error, "OAuth authorization returned no code" if callback_result["code"].to_s.empty?
+
+          token = token_request(metadata.fetch("token_endpoint"), {
+            "grant_type" => "authorization_code",
+            "code" => callback_result.fetch("code"),
+            "redirect_uri" => redirect_uri,
+            "client_id" => client.fetch("client_id"),
+            "code_verifier" => verifier
+          })
+          grant = normalize_token(token).merge(
+            "client_id" => client.fetch("client_id"),
+            "client_secret" => client["client_secret"],
+            "token_endpoint_auth_method" => client["token_endpoint_auth_method"] || "none",
+            "token_endpoint" => metadata.fetch("token_endpoint"),
+            "authorization_server" => metadata.fetch("issuer"),
+            "resource" => @config.resource
+          )
+          @store.save(grant)
+        ensure
+          receiver.close if defined?(receiver) && receiver.respond_to?(:close)
+        end
+
+        def refresh(grant)
+          refresh_token = grant["refresh_token"].to_s
+          raise Error, "OAuth refresh token is missing; log in again" if refresh_token.empty?
+
+          fields = {
+            "grant_type" => "refresh_token",
+            "refresh_token" => refresh_token,
+            "client_id" => grant.fetch("client_id")
+          }
+          token = token_request(grant.fetch("token_endpoint"), fields,
+                                client_secret: grant["client_secret"],
+                                auth_method: grant["token_endpoint_auth_method"])
+          updated = grant.merge(normalize_token(token))
+          updated["refresh_token"] = refresh_token if token["refresh_token"].to_s.empty?
+          updated
+        rescue KeyError
+          raise Error, "stored OAuth grant is incomplete; log in again"
+        end
+
+        private def discover_metadata(explicit_resource_metadata_url)
+          protected_url = explicit_resource_metadata_url || default_resource_metadata_url
+          protected = get_json(protected_url, "protected resource metadata")
+          if protected["resource"] && protected["resource"] != @config.resource
+            raise Error, "OAuth protected resource metadata does not match the configured MCP resource"
+          end
+
+          server = Array(protected["authorization_servers"]).first || protected["authorization_server"]
+          server = validate_https_url(server, "authorization server")
+          metadata_url = "#{server.sub(%r{/\z}, '')}/.well-known/oauth-authorization-server"
+          metadata = get_json(metadata_url, "authorization server metadata")
+          metadata["issuer"] ||= server
+          %w[issuer authorization_endpoint token_endpoint registration_endpoint].each do |key|
+            metadata[key] = validate_https_url(metadata[key], key.tr("_", " "))
+          end
+          raise Error, "authorization server metadata issuer does not match" unless metadata["issuer"] == server
+          unless Array(metadata["code_challenge_methods_supported"]).include?("S256")
+            raise Error, "authorization server does not support PKCE S256"
+          end
+          metadata
+        end
+
+        private def default_resource_metadata_url
+          resource = URI.parse(@config.resource)
+          origin = "#{resource.scheme}://#{resource.host}"
+          origin += ":#{resource.port}" unless resource.port == 443
+          "#{origin}/.well-known/oauth-protected-resource#{resource.path}"
+        end
+
+        private def register_client(metadata, redirect_uri)
+          response = @requester.call("POST", metadata.fetch("registration_endpoint"),
+                                     { "Content-Type" => "application/json" },
+                                     JSON.generate(
+                                       "client_name" => "openclacky",
+                                       "application_type" => "native",
+                                       "redirect_uris" => [redirect_uri],
+                                       "grant_types" => %w[authorization_code refresh_token],
+                                       "response_types" => ["code"],
+                                       "token_endpoint_auth_method" => "none",
+                                       "scope" => "openid profile email offline_access"
+                                     ))
+          client = parse_success_json(response, "OAuth client registration")
+          raise Error, "OAuth client registration returned no client_id" if client["client_id"].to_s.empty?
+          client
+        end
+
+        private def build_authorization_url(metadata, client_id, redirect_uri, verifier, state)
+          uri = URI.parse(metadata.fetch("authorization_endpoint"))
+          uri.query = URI.encode_www_form(
+            "response_type" => "code",
+            "client_id" => client_id,
+            "redirect_uri" => redirect_uri,
+            "scope" => "openid profile email offline_access",
+            "code_challenge" => self.class.pkce_challenge(verifier),
+            "code_challenge_method" => "S256",
+            "state" => state,
+            "resource" => @config.resource
+          )
+          uri.to_s
+        end
+
+        private def token_request(url, fields, client_secret: nil, auth_method: nil)
+          headers = { "Content-Type" => "application/x-www-form-urlencoded" }
+          if client_secret && auth_method == "client_secret_basic"
+            credentials = Base64.strict_encode64("#{fields['client_id']}:#{client_secret}")
+            headers["Authorization"] = "Basic #{credentials}"
+          elsif client_secret
+            fields = fields.merge("client_secret" => client_secret)
+          end
+          response = @requester.call("POST", validate_https_url(url, "token endpoint"), headers,
+                                     URI.encode_www_form(fields))
+          parse_success_json(response, "OAuth token exchange")
+        end
+
+        private def normalize_token(token)
+          access_token = token["access_token"].to_s
+          raise Error, "OAuth token response contained no access token" if access_token.empty?
+          {
+            "access_token" => access_token,
+            "refresh_token" => token["refresh_token"],
+            "token_type" => token["token_type"] || "Bearer",
+            "expires_at" => @clock.call + token.fetch("expires_in", 3600).to_i
+          }
+        end
+
+        private def get_json(url, label)
+          response = @requester.call("GET", validate_https_url(url, label), { "Accept" => "application/json" }, nil)
+          parse_success_json(response, label)
+        end
+
+        private def parse_success_json(response, label)
+          status = response.status.to_i
+          raise Error, "#{label} failed with HTTP #{status}" unless status >= 200 && status < 300
+          body = response.body.to_s
+          raise Error, "#{label} response was too large" if body.bytesize > MAX_RESPONSE_BYTES
+          value = JSON.parse(body)
+          raise JSON::ParserError unless value.is_a?(Hash)
+          value
+        rescue JSON::ParserError
+          raise Error, "#{label} returned invalid JSON"
+        end
+
+        private def validate_https_url(value, label)
+          uri = URI.parse(value.to_s)
+          unless uri.scheme == "https" && uri.host && !uri.host.empty? && !uri.user && !uri.password
+            raise Error, "#{label} must be an HTTPS URL without credentials"
+          end
+          uri.to_s
+        rescue URI::InvalidURIError
+          raise Error, "#{label} must be an HTTPS URL"
+        end
+
+        private def request(method, url, headers, body)
+          uri = URI.parse(url)
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+          http.open_timeout = 10
+          http.read_timeout = 30
+          request_class = method == "GET" ? Net::HTTP::Get : Net::HTTP::Post
+          request = request_class.new(uri.request_uri)
+          headers.each { |key, value| request[key] = value }
+          request.body = body if body
+          response = http.request(request)
+          Response.new(response.code.to_i, response.each_header.to_h, response.body.to_s)
+        rescue StandardError => e
+          raise Error, "OAuth network request failed (#{e.class})"
+        end
+
+        class CallbackReceiver
+          attr_reader :redirect_uri
+
+          def initialize(timeout: 300)
+            @server = TCPServer.new("127.0.0.1", 0)
+            @timeout = timeout
+            @redirect_uri = "http://127.0.0.1:#{@server.addr[1]}/callback"
+          end
+
+          def call(authorization_url, _expected_state)
+            open_browser(authorization_url)
+            socket = Timeout.timeout(@timeout) { @server.accept }
+            request_line = socket.gets.to_s
+            path = request_line.split(" ")[1].to_s
+            query = URI.decode_www_form(URI.parse(path).query.to_s).to_h
+            socket.write("HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nConnection: close\r\n\r\nOpenClacky authorization complete. You may close this tab.\n")
+            query
+          rescue Timeout::Error
+            raise Error, "OAuth authorization timed out"
+          ensure
+            socket.close if defined?(socket) && socket
+          end
+
+          def close
+            @server.close unless @server.closed?
+          end
+
+          private def open_browser(url)
+            command = if RUBY_PLATFORM.include?("darwin")
+                        ["open", url]
+                      elsif RUBY_PLATFORM =~ /mswin|mingw|cygwin/
+                        ["cmd", "/c", "start", "", url]
+                      else
+                        ["xdg-open", url]
+                      end
+            opened = system(*command, out: File::NULL, err: File::NULL)
+            raise Error, "could not open a browser for OAuth authorization" unless opened
+          end
+        end
+      end
+    end
+  end
+end

data/lib/clacky/mcp/oauth/config.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Clacky
+  module Mcp
+    module OAuth
+      class Config
+        class Error < StandardError; end
+
+        attr_reader :resource
+
+        def self.from_server_spec(spec)
+          spec ||= {}
+          auth = spec["auth"]
+          enabled = auth.is_a?(Hash) && !auth.empty?
+          if enabled && auth["type"].to_s != "oauth"
+            raise Error, "unsupported MCP authentication type '#{auth['type']}'"
+          end
+
+          resource = enabled ? (auth["resource"] || spec["url"]) : spec["url"]
+          new(enabled: enabled, resource: resource, endpoint: spec["url"])
+        end
+
+        def initialize(enabled:, resource:, endpoint: nil)
+          @enabled = enabled
+          @resource = resource.to_s
+          @endpoint = (endpoint || resource).to_s
+          validate! if enabled?
+        end
+
+        def enabled?
+          @enabled == true
+        end
+
+        private def validate!
+          validate_https_url(@endpoint, "OAuth MCP endpoint")
+          validate_https_url(@resource, "OAuth MCP resource")
+        end
+
+        private def validate_https_url(value, label)
+          uri = URI.parse(value)
+          raise Error, "#{label} must be an HTTPS URL without credentials" unless
+            uri.scheme == "https" && uri.host && !uri.host.empty? && !uri.user && !uri.password
+        rescue URI::InvalidURIError
+          raise Error, "#{label} must be an HTTPS URL"
+        end
+      end
+    end
+  end
+end

data/lib/clacky/mcp/oauth/credential_store.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+require "digest"
+
+module Clacky
+  module Mcp
+    module OAuth
+      class CredentialStore
+        class Error < StandardError; end
+
+        attr_reader :path
+
+        def initialize(server_name:, home: Dir.home)
+          original_name = server_name.to_s
+          safe_name = original_name.gsub(/[^a-zA-Z0-9_.-]/, "_")
+          safe_name = "server" if safe_name.empty?
+          safe_name = "#{safe_name}-#{Digest::SHA256.hexdigest(original_name)[0, 12]}" if safe_name != original_name
+          @path = File.join(File.expand_path(home), ".clacky", "mcp", "oauth", "#{safe_name}.json")
+        end
+
+        def load
+          return nil unless File.file?(@path)
+
+          with_lock(File::LOCK_SH) do
+            value = JSON.parse(File.read(@path))
+            raise JSON::ParserError unless value.is_a?(Hash)
+            value
+          end
+        rescue JSON::ParserError
+          raise Error, "invalid OAuth credential file; log in again"
+        end
+
+        def save(value)
+          ensure_directory
+          with_lock(File::LOCK_EX) do
+            temporary = "#{@path}.tmp-#{Process.pid}-#{rand(1_000_000)}"
+            File.open(temporary, File::WRONLY | File::CREAT | File::EXCL, 0o600) do |file|
+              file.write(JSON.generate(value))
+              file.write("\n")
+              file.flush
+              file.fsync
+            end
+            File.rename(temporary, @path)
+            File.chmod(0o600, @path)
+          ensure
+            FileUtils.rm_f(temporary) if defined?(temporary) && temporary
+          end
+          value
+        end
+
+        def delete
+          return unless File.exist?(@path)
+
+          ensure_directory
+          with_lock(File::LOCK_EX) { FileUtils.rm_f(@path) }
+        end
+
+        def inspect
+          "#<#{self.class} path=#{@path.inspect}>"
+        end
+
+        private def ensure_directory
+          FileUtils.mkdir_p(File.dirname(@path), mode: 0o700)
+          File.chmod(0o700, File.dirname(@path))
+        end
+
+        private def with_lock(mode)
+          ensure_directory
+          lock_path = "#{@path}.lock"
+          File.open(lock_path, File::RDWR | File::CREAT, 0o600) do |lock|
+            lock.flock(mode)
+            yield
+          ensure
+            lock.flock(File::LOCK_UN) rescue nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/clacky/mcp/oauth/session.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module Clacky
+  module Mcp
+    module OAuth
+      class Session
+        EXPIRY_SKEW = 60
+
+        class Error < StandardError; end
+        class NotConnectedError < Error; end
+
+        def initialize(store:, manager:, clock: nil)
+          @store = store
+          @manager = manager
+          @clock = clock || -> { Time.now.to_i }
+          @force_refresh = false
+          @lock = Monitor.new
+        end
+
+        def authorization_headers
+          @lock.synchronize do
+            grant = @store.load
+            raise NotConnectedError, "OAuth MCP is not connected; run `clacky mcp login SERVER`" unless grant
+
+            if @force_refresh || expiring?(grant)
+              grant = @manager.refresh(grant)
+              @store.save(grant)
+              @force_refresh = false
+            end
+            token = grant["access_token"].to_s
+            raise Error, "stored OAuth grant has no access token; log in again" if token.empty?
+            { "Authorization" => "Bearer #{token}" }
+          end
+        rescue NotConnectedError, Error
+          raise
+        rescue StandardError => e
+          raise Error, "OAuth session failed (#{e.class}); log in again"
+        end
+
+        def invalidate!
+          @lock.synchronize { @force_refresh = true }
+        end
+
+        def login
+          @lock.synchronize do
+            grant = @manager.login
+            @force_refresh = false
+            grant
+          end
+        end
+
+        def logout
+          @lock.synchronize do
+            @store.delete
+            @force_refresh = false
+          end
+          true
+        end
+
+        def connected?
+          !@store.load.nil?
+        rescue StandardError
+          false
+        end
+
+        def status
+          grant = @store.load
+          return { "connected" => false } unless grant
+          {
+            "connected" => true,
+            "expires_at" => grant["expires_at"],
+            "expired" => grant.fetch("expires_at", 0).to_i <= @clock.call
+          }
+        end
+
+        def inspect
+          "#<#{self.class} connected=#{connected?}>"
+        end
+
+        private def expiring?(grant)
+          grant.fetch("expires_at", 0).to_i <= @clock.call + EXPIRY_SKEW
+        end
+      end
+    end
+  end
+end

data/lib/clacky/message_format/anthropic.rb

@@ -19,6 +19,25 @@ module Clacky
     module Anthropic
       module_function
 
+      # Normalise a /v1/messages usage block to the codebase's canonical
+      # (OpenAI-style) prompt_tokens: total input including cache_read but
+      # excluding cache_creation.
+      #
+      # Anthropic reports input_tokens as the post-breakpoint tail only, with
+      # the cache buckets disjoint from it. Some /v1/messages-compatible
+      # gateways instead report input_tokens as the FULL input with both cache
+      # buckets already folded in; adding cache_read there would bill the whole
+      # cached prefix twice. Detect that by whether the cache buckets already
+      # fit inside input_tokens.
+      def normalise_prompt_tokens(input_tokens, cache_read, cache_creation)
+        cached_input = cache_read + cache_creation
+        if cached_input.positive? && input_tokens >= cached_input
+          input_tokens - cache_creation
+        else
+          input_tokens + cache_read
+        end
+      end
+
       # ── Message type identification ───────────────────────────────────────────
 
       # Returns true if the message is an Anthropic-native tool result stored in
@@ -169,22 +188,16 @@ module Clacky
                         else data["stop_reason"]
                         end
 
-        # Anthropic native `input_tokens` counts ONLY the non-cached, freshly-billed
-        # input — cache_read_input_tokens and cache_creation_input_tokens are
-        # reported separately and are disjoint from input_tokens.
-        #
         # Normalise to the codebase's canonical shape (OpenAI-style) so downstream
         # (ModelPricing.calculate_cost, CostTracker, show_token_usage) stays
         # provider-agnostic:
         #
-        #   prompt_tokens     = non_cached + cache_read     (OpenAI convention:
-        #                                                    includes cache_read
-        #                                                    but NOT cache_write;
-        #                                                    ModelPricing does
-        #                                                    `regular_input = prompt_tokens - cache_read`.)
+        #   prompt_tokens     = total input incl. cache_read, excl. cache_write
+        #                       (ModelPricing does
+        #                        `regular_input = prompt_tokens - cache_read`.)
         #   completion_tokens = output
         #   total_tokens      = THIS TURN'S new compute volume
-        #                     = raw_input + cache_creation + output
+        #                     = non_cached + cache_creation + output
         #                       (cache_read is excluded because hits are ~free /
         #                        already-paid-for; cache_creation IS new work this
         #                        turn even though it's billed at write_rate.)
@@ -199,14 +212,15 @@ module Clacky
         cache_creation    = usage["cache_creation_input_tokens"].to_i
         output_tokens     = usage["output_tokens"].to_i
 
-        prompt_tokens = raw_input_tokens + cache_read
+        prompt_tokens = normalise_prompt_tokens(raw_input_tokens, cache_read, cache_creation)
 
         usage_data = {
           prompt_tokens:      prompt_tokens,
           completion_tokens:  output_tokens,
           # Per-turn new compute: what the server freshly processed this request.
-          # Excludes cache_read (nearly free, already-paid-for).
-          total_tokens:       raw_input_tokens + cache_creation + output_tokens,
+          # Excludes cache_read (nearly free, already-paid-for). Derived from the
+          # normalised prompt_tokens so it stays correct under both conventions.
+          total_tokens:       (prompt_tokens - cache_read) + cache_creation + output_tokens,
           # Signal to CostTracker: total_tokens above is already the per-turn
           # delta (not a running cumulative like OpenAI's). CostTracker should
           # NOT subtract previous_total when this flag is truthy.

data/lib/clacky/message_history.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 module Clacky
   # MessageHistory wraps the conversation message list and exposes
   # business-meaningful operations instead of raw array manipulation.
@@ -12,9 +14,18 @@ module Clacky
       task_id created_at system_injected session_context memory_update
       subagent_instructions subagent_result subagent_transcript token_usage
       compressed_summary chunk_path truncated transient
-      chunk_index chunk_count
+      chunk_index chunk_count ext_events
     ].freeze
 
+    # Cap on persisted ext_events per message. These are milestone events
+    # (progress chatter is transient), so a handful per message is the norm —
+    # the cap only exists to stop a runaway extension. Oldest are dropped first.
+    MAX_EXT_EVENTS_PER_MESSAGE = 50
+
+    # Oversized payloads belong in a file, not in session.json (which is
+    # rewritten in full on every save).
+    MAX_EXT_EVENT_BYTES = 8 * 1024
+
     def initialize(messages = [])
       @messages = messages.dup
     end
@@ -85,6 +96,26 @@ module Clacky
       self
     end
 
+    # Append a custom extension event onto the most recent message so it is
+    # persisted with the session and can be replayed after a reload.
+    # Events are anchored to the last message: on replay they are re-emitted
+    # right after that message, preserving chronological order.
+    # No-op when the history is still empty (nothing to anchor to).
+    def append_ext_event(event)
+      msg = @messages.last
+      return self unless msg
+
+      if JSON.generate(event).bytesize > MAX_EXT_EVENT_BYTES
+        Clacky::Logger.warn("ext event #{event[:type].inspect} dropped: payload exceeds #{MAX_EXT_EVENT_BYTES} bytes")
+        return self
+      end
+
+      list = (msg[:ext_events] ||= [])
+      list.shift while list.size >= MAX_EXT_EVENTS_PER_MESSAGE
+      list << deep_sanitize_utf8(event)
+      self
+    end
+
     # Mutate the last message matching the predicate lambda in-place.
     # Used by execute_skill_with_subagent to update instruction messages.
     def mutate_last_matching(predicate, &block)