ask-agent 0.24.1 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5268e3474f109d7471749692a535a89b266e5a9d10c20499a565087500eaee8
-  data.tar.gz: 24fc0068d51f1eedc2e0d6f427234db468db375e915a4383533086993dab8b5d
+  metadata.gz: bbb7c5376d7ba7cf03099123c5aab9f12dd9a10efca9906fd07ea2782b28d296
+  data.tar.gz: 8c82d88e763cdf7e765fec8837b22ab5dc8a5a7cbaca01d9ffff59c8328a1e99
 SHA512:
-  metadata.gz: 8dddca135834b42108d217fc09a121a4fc4fd4ad44da326849b9654f30ba393bc115b44a3bc756433a7cbb8bd1b729d02dc246feb540e6f0ff39dc2aff1e56ad
-  data.tar.gz: 5cde0691f9aa8bd6723c20344211c50cc18e15ffdf392d97710896d4752b8343c583faab5de7e4156e261049676dbe06e2136162a8d10d1b48e9ae3e174f7786
+  metadata.gz: f886aedfbed678ce466c545e9f20255320a5ac77930c60d164613e833345455c52de0256f9c1a9357cda6040a79c2f17ed6aa687c5b8f135c6d355a50ecea5b6
+  data.tar.gz: be66be79539f4f284c8741ec634f17c4e5a12d18e4cc182209be5ac5f8988101589b10dfe331234cc1bb6880aa1a2c0af0ffbe4817b9ab382dd3fbcb2d6fd6b1

data/CHANGELOG.md

@@ -1,3 +1,65 @@
+## [0.25.0] — 2026-08-02
+
+### Added
+
+- **Model-aware compaction reserve.** `Ask::Agent::Compactor` now derives
+  its context headroom from the model's declared `max_output_tokens`
+  (capped at 20,000) instead of a fixed 80% threshold. When the model
+  metadata is unavailable, a static 20,000-token reserve applies. A safety
+  floor clamps the reserve for tiny-window models so compaction can fire
+  usefully instead of triggering on every turn.
+
+  ```ruby
+  # Default: compact when tokens exceed context_window - reserve
+  compactor = Ask::Agent::Compactor.new
+
+  # Legacy behavior: compact at 80% of the window
+  compactor = Ask::Agent::Compactor.new(threshold: 0.8)
+
+  # Explicit headroom
+  compactor = Ask::Agent::Compactor.new(reserve_tokens: 5_000)
+  ```
+
+- **Token-aware recent tail.** `keep_recent_tokens:` preserves the last N
+  tokens of conversation verbatim (default 8,000) and summarizes only what's
+  older — recent-context fidelity depends on the active work, not message
+  counts. When not configured, the legacy fixed message-count tail
+  (`keep_count:`, default 8) is used for backward compatibility.
+
+- **Global compaction options** on `Ask::Agent.configure`:
+  `compactor_reserve_tokens` and `compactor_keep_recent_tokens` apply to all
+  sessions. `compactor_threshold` now defaults to `nil` (reserve mode).
+
+- **`Compactor#compact_threshold_tokens`** — public accessor for the token
+  count at which compaction triggers (window × threshold, or
+  window − reserve).
+
+### Fixed
+
+- **`microcompact!` no longer crashes on long tool results.** `Ask::Message`
+  is immutable — `content=` never existed. The method now rebuilds the
+  message in place via `map!`, preserving `tool_call_id` and metadata.
+
+### Changed
+
+- `Compactor#extract_summary` is now public.
+
+## [0.24.2] — 2026-07-30
+
+### Fixed
+
+- **Definitions discovered through an intermediate base class no longer
+  crash.** `Definition.inherited` appended to `@subclasses` on `self`, so
+  subclassing `Ask::Agent::Definition` through an application base class
+  (e.g. `class Agent < ApplicationAgent` in a Rails app) made the ivar nil
+  and raised `NoMethodError` on load. Tracking now reads the registry from
+  `Definition` itself, and `Definition.subclasses` reports the same list
+  regardless of receiver.
+
+- **Changelog for 0.24.1.** The subclass-chain fix shipped as 0.24.1
+  without a changelog entry; it is documented here and republished as
+  0.24.2 so the gem content includes it.
+
 ## [0.24.0] — 2026-07-30
 
 ### Changed

data/lib/ask/agent/compactor.rb

@@ -2,6 +2,26 @@
 
 module Ask
   module Agent
+    # Context compaction for long sessions. When conversation tokens approach
+    # the model's context window, older messages are summarized and replaced
+    # with a structured summary, preserving a recent tail verbatim.
+    #
+    # Trigger modes:
+    # 1. Threshold — tokens exceed (context_window - reserve). Compact, no retry.
+    # 2. Overflow — LLM returned context overflow. Compact, then auto-retry.
+    #
+    # Reserve is model-aware: it defaults to the model's declared max output
+    # tokens (capped at {DEFAULT_RESERVE_TOKENS}), so compaction leaves exactly
+    # the headroom a single turn can consume. For models without declared
+    # limits, a static default applies. A safety floor clamps the reserve for
+    # tiny-window models so threshold compaction can fire usefully instead of
+    # triggering on every turn.
+    #
+    # The recent tail is also token-aware: {keep_recent_tokens} preserves the
+    # last N tokens of conversation verbatim (recent-context fidelity depends
+    # on the active work, not on message counts) and summarizes only what's
+    # older. When not configured, the legacy fixed message-count behavior is
+    # used for backward compatibility.
     class Compactor
       CONTEXT_WINDOWS = {
         "gpt-4o" => 128_000,
@@ -15,25 +35,76 @@ module Ask
         "deepseek-v4-pro" => 1_000_000,
       }.tap { |h| h.default = 128_000 }
 
+      # Default headroom reserved for a single model turn when the model's
+      # max output tokens are unknown.
+      DEFAULT_RESERVE_TOKENS = 20_000
+
+      # Default verbatim recent-context tail preserved during compaction.
+      DEFAULT_KEEP_RECENT_TOKENS = 8_000
+
+      # Minimum reserve for tiny-window models (safety floor).
+      MIN_RESERVE_TOKENS = 1_024
+
+      # Legacy fixed message-count tail (backward compatibility).
+      DEFAULT_KEEP_COUNT = 8
+
+      # Conversations smaller than this are never compacted.
+      MIN_MESSAGES = 6
+
       attr_accessor :chat, :llm
 
-      def initialize(threshold: 0.8, strategy: :proactive, llm: nil)
+      # @param threshold [Float, nil] Compact when tokens exceed
+      #   context_window * threshold. When nil (default), compaction triggers
+      #   at context_window - reserve_tokens (model-aware).
+      # @param strategy [Symbol] Reserved; :proactive is the only strategy.
+      # @param llm [Object, String, nil] LLM used for summarization. When nil,
+      #   a heuristic summary is generated instead.
+      # @param reserve_tokens [Integer, nil] Explicit headroom for one turn.
+      #   When nil, derived from the model's max output tokens (see
+      #   {#derive_reserve}).
+      # @param keep_recent_tokens [Integer, nil] Explicit verbatim recent-tail
+      #   budget. When nil, the legacy fixed message-count tail is preserved.
+      # @param keep_count [Integer] Legacy fixed tail in messages when
+      #   keep_recent_tokens is nil.
+      # @param min_messages [Integer] Conversations with fewer messages are
+      #   never compacted.
+      def initialize(threshold: nil, strategy: :proactive, llm: nil,
+                     reserve_tokens: nil, keep_recent_tokens: nil,
+                     keep_count: DEFAULT_KEEP_COUNT, min_messages: MIN_MESSAGES)
         @threshold = threshold
         @strategy = strategy
         @llm = llm
+        @reserve_tokens = reserve_tokens
+        @keep_recent_tokens = keep_recent_tokens
+        @keep_count = keep_count
+        @min_messages = min_messages
         @already_compacted = false
         @overflow_recovered = false
       end
 
       def overflow_recovered? = @overflow_recovered
 
+      # Whether the conversation is close enough to the model's window that
+      # compaction should run. Triggers at either threshold mode
+      # (window * threshold) or reserve mode (window - reserve).
       def should_compact?
         return false unless @chat
-        current = estimate_total_tokens
+        estimate_total_tokens >= compact_threshold_tokens
+      end
+
+      # The token count at which compaction triggers.
+      #
+      # @return [Integer]
+      def compact_threshold_tokens
         window = context_window
-        current >= window * @threshold
+        return (window * @threshold).round if @threshold
+
+        window - reserve_tokens
       end
 
+      # Run compaction, emitting start/end events.
+      #
+      # @param event_emitter [#emit, nil]
       def run(event_emitter: nil)
         return unless @chat
 
@@ -45,14 +116,16 @@ module Ask
         event_emitter&.emit(Events::CompactionEnd.new(tokens_before: tokens_before, tokens_after: tokens_after, summary: extract_summary))
       end
 
+      # Summarize older messages and replace them with a summary, preserving
+      # a recent tail. The tail is either token-based ({keep_recent_tokens})
+      # or the legacy fixed message count.
       def compact!
         return unless @chat
         messages = @chat.messages.dup
-        return if messages.size < 6
+        return if messages.size < @min_messages
 
-        keep_count = [messages.size, 8].min
-        recent = messages.last(keep_count)
-        older = messages.first(messages.size - keep_count)
+        split_index = find_split_index(messages)
+        older = messages.first(split_index)
         return if older.empty?
 
         summary = if @llm
@@ -65,36 +138,148 @@ module Ask
         @chat.add_message(role: :system, content: "[Previous conversation summary]: #{summary}")
       end
 
+      # Aggressive overflow fallback: clears oversized tool results in place,
+      # keeping the conversation structure intact.
       def microcompact!
         return unless @chat
-        @chat.messages.each do |msg|
-          next unless msg.role == :tool
-          msg.content = "[Tool result cleared by compaction]" if msg.content.to_s.length > 200
+        @chat.messages.map! do |msg|
+          next msg unless msg.role == :tool
+          next msg unless msg.content.to_s.length > 200
+
+          Ask::Message.new(
+            role: :tool,
+            content: "[Tool result cleared by compaction]",
+            tool_call_id: msg.tool_call_id,
+            metadata: msg.metadata
+          )
         end
       end
 
+      # Recover from a context-overflow error: compact once, then fall back
+      # to micro-compaction on subsequent overflows in the same session.
       def recover_from_overflow
         if @already_compacted then microcompact! else compact! end
         @already_compacted = true
         @overflow_recovered = true
       end
 
+      # Rough token estimate: ~4 characters per token.
+      #
+      # @param text [String]
+      # @return [Integer]
       def estimate_tokens(text)
         (text.to_s.length / 4.0).ceil
       end
 
+      # Total estimated tokens across all messages, including tool-call
+      # payloads.
+      #
+      # @return [Integer]
       def estimate_total_tokens
         return 0 unless @chat
         @chat.messages.sum { |msg| estimate_message_tokens(msg) }
       end
 
+      # The model's context window. Consulted from the model catalog first,
+      # then the bundled table, then the default.
+      #
+      # @return [Integer]
       def context_window
-        model = @chat.model.to_s
-        CONTEXT_WINDOWS[model]
+        info = model_info
+        return info.context_window if info&.context_window
+
+        CONTEXT_WINDOWS[@chat.model.to_s] || CONTEXT_WINDOWS.default
+      end
+
+      # Headroom reserved for one model turn. Explicit value wins; otherwise
+      # derived from the model's max output tokens with a safety floor.
+      #
+      # @return [Integer]
+      def reserve_tokens
+        @reserve_tokens || derive_reserve
+      end
+
+      # Verbatim recent-tail budget in tokens.
+      #
+      # @return [Integer]
+      def keep_recent_tokens
+        @keep_recent_tokens || DEFAULT_KEEP_RECENT_TOKENS
+      end
+
+      # The text of the most recent injected summary, or "" if none exists.
+      #
+      # @return [String]
+      def extract_summary
+        @chat.messages.each { |msg| return msg.content.to_s if msg.content.to_s.start_with?("[Previous conversation summary]") }
+        ""
       end
 
       private
 
+      def model_info
+        Ask::ModelCatalog.find(@chat.model.to_s)
+      rescue Ask::ModelNotFound, NameError
+        nil
+      end
+
+      # Derive the reserve from the model's declared max output tokens,
+      # capped at {DEFAULT_RESERVE_TOKENS}. Applies a safety floor for
+      # tiny-window models: if the reserve would consume half or more of the
+      # window, clamp it to a third so threshold compaction can fire usefully
+      # instead of triggering on every turn.
+      #
+      # @return [Integer]
+      def derive_reserve
+        info = model_info
+        max_output = info&.max_output_tokens.to_i
+        reserve = if max_output > 0
+          [DEFAULT_RESERVE_TOKENS, max_output].min
+        else
+          DEFAULT_RESERVE_TOKENS
+        end
+
+        window = context_window
+        if window > 0 && reserve * 2 >= window
+          reserve = [MIN_RESERVE_TOKENS, window / 3].max
+        end
+        reserve
+      end
+
+      # Index of the first message in the recent tail. Token-based when
+      # keep_recent_tokens is configured; otherwise the legacy fixed
+      # message-count tail.
+      #
+      # @param messages [Array<Ask::Message>]
+      # @return [Integer]
+      def find_split_index(messages)
+        if @keep_recent_tokens
+          find_token_split_index(messages)
+        else
+          [messages.size - @keep_count, 0].max
+        end
+      end
+
+      # Walk from the end of the conversation accumulating tokens until the
+      # keep_recent_tokens budget is consumed. The split never keeps fewer
+      # than MIN_MESSAGES recent messages — the tail always retains a recent
+      # exchange intact.
+      #
+      # @param messages [Array<Ask::Message>]
+      # @return [Integer]
+      def find_token_split_index(messages)
+        budget = keep_recent_tokens
+        index = messages.size
+
+        messages.reverse_each do |msg|
+          budget -= estimate_message_tokens(msg)
+          index -= 1
+          break if budget <= 0
+        end
+
+        # Never keep fewer than MIN_MESSAGES recent messages
+        [index, messages.size - MIN_MESSAGES].min
+      end
+
       def estimate_message_tokens(message)
         base = estimate_tokens(message.content.to_s)
         if message.tool_call? && message.respond_to?(:tool_calls) && message.tool_calls
@@ -141,11 +326,6 @@ module Ask
         elsif @llm.is_a?(String) then Ask::Agent::Chat.new(model: @llm)
         else Ask::Agent::Chat.new(model: Ask::Agent.configuration.default_model) end
       end
-
-      def extract_summary
-        @chat.messages.each { |msg| return msg.content.to_s if msg.content.to_s.start_with?("[Previous conversation summary]") }
-        ""
-      end
     end
   end
 end

data/lib/ask/agent/configuration.rb

@@ -6,7 +6,7 @@ module Ask
       attr_accessor :default_model, :default_provider, :default_max_turns,
                     :compactor_enabled, :compactor_threshold, :parallel_tool_execution,
                     :max_tool_retries, :prompt_caching, :default_evaluator_model,
-                    :audit_log
+                    :audit_log, :compactor_reserve_tokens, :compactor_keep_recent_tokens
 
       # @return [Middleware::Pipeline] the middleware pipeline for provider calls
       attr_reader :middleware
@@ -18,7 +18,9 @@ module Ask
         @default_model = "gpt-4o"
         @default_max_turns = 25
         @compactor_enabled = true
-        @compactor_threshold = 0.8
+        @compactor_threshold = nil
+        @compactor_reserve_tokens = nil
+        @compactor_keep_recent_tokens = nil
         @parallel_tool_execution = true
         @max_tool_retries = 3
         @prompt_caching = true

data/lib/ask/agent/session.rb

@@ -364,9 +364,14 @@ module Ask
       end
 
       def build_compactor(config)
+        global = Ask::Agent.configuration
         compactor = Compactor.new(
-          threshold: config[:threshold] || 0.8,
-          strategy: config[:strategy] || :proactive
+          threshold: config[:threshold] || global.compactor_threshold,
+          strategy: config[:strategy] || :proactive,
+          reserve_tokens: config[:reserve_tokens] || global.compactor_reserve_tokens,
+          keep_recent_tokens: config[:keep_recent_tokens] || global.compactor_keep_recent_tokens,
+          keep_count: config[:keep_count],
+          min_messages: config[:min_messages]
         )
         compactor.chat = @chat
         compactor

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.24.1"
+    VERSION = "0.25.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-agent
 version: !ruby/object:Gem::Version
-  version: 0.24.1
+  version: 0.25.0
 platform: ruby
 authors:
 - Kaka Ruto