ask-agent 0.24.2 → 0.25.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c4f30ce069402dd4a125120e13e63fbbb438ca2270cd683a199d8f774d93b40c
-  data.tar.gz: db1e37fea28111e58ac75723d483019c6e13bec7ed0fa4b3ed0c81dcbda0621d
+  metadata.gz: d6d5dd31344228811bd4c7993547c9e0f9d7c39c779f58250d82ad95f271bd7d
+  data.tar.gz: ba08c57e9fc7dfc410e6a835ffab1076d1f4b5704bee866f7a38e158da712d34
 SHA512:
-  metadata.gz: 2d4562819a0a62a758e173ef3473800880c3da920a1bf00466933a1ff39a488e6cfc35b82e89429add6c5a255f4593888e48c191bed4c286324da0a5132bec5a
-  data.tar.gz: d1f94898e2155cf63d8ef04e6e458582ef9fed2c5b74adf007a27c1562bd0958165a79070612b5a08cca87b18e16e216fc6efd5352e79a39e6f76d94b0d4fe5a
+  metadata.gz: 5d46b653b22b50dee9597238cc65ce5fe72c3840322e1ecd03efccfe6494a4494bff473f3bc3c4eff1ae56df849142a45f52bc77e23c9a93a9c240f465d7db68
+  data.tar.gz: 9c158ab0aa0be906723681458ea54d90b15cd7289647e7acb8527faf367ead4490919a84b0a2e71186b4b93945ac065db063a33ead26b2532d0d50efd2dd8bf3

data/CHANGELOG.md

@@ -1,3 +1,70 @@
+## [0.25.2] - 2026-08-03
+
+### Fixed
+
+- **Streaming no longer depends on ActiveSupport's `String#truncate`.** The
+  SSE event serialization (streaming.rb) and the max-consecutive-tool-turns
+  summary (loop.rb) called `String#truncate`, which only exists when
+  ActiveSupport's core extensions are loaded — so a bare `require
+  "ask-agent"` raised `NoMethodError` as soon as a tool emitted a partial
+  result. Both call sites now use a plain-Ruby truncation helper.
+
+## [0.25.1] - 2026-08-02
+
+### Fixed
+
+- **Session passes resolved tool instances to Chat.** Tool classes passed
+  as `tools: [MyTool]` were resolved for the session but handed to the
+  underlying Chat unresolved, so `ToolDef.from_tool` used `Class#name`
+  and raised `Ask::InvalidToolDefinition` on the first run. Sessions now
+  resolve tools before building the Chat; classes and instances both work.
+
+## [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

data/README.md

@@ -1,8 +1,9 @@
 # ask-agent
 
-Agent runtime for the ask-rb ecosystem. The core agent loop: think → call tools → execute → feed back → repeat.
-
-Ported from `RubyLLM::Conductor` into the `Ask::Agent` namespace.
+Agent runtime for the ask-rb ecosystem. Runs the core agent loop: think, call
+tools, execute, feed results back, and repeat until the task is done. Built on
+ask-core, ask-state-providers, ask-llm-providers, ask-tools, ask-skills, and
+ask-instrumentation, and it powers the `askr` CLI.
 
 ## Installation
 
@@ -15,114 +16,12 @@ gem "ask-agent"
 ```ruby
 require "ask-agent"
 
-session = Ask::Agent::Session.new(
-  model: "gpt-4o",
-  tools: [Ask::Tools::Shell::Bash, Ask::Tools::Shell::Read]
-)
-
+session = Ask::Agent::Session.new(model: "gpt-4o", max_turns: 25)
 response = session.run("What files are in the current directory?")
 puts response
 ```
 
-## Components
-
-| Component | File | Purpose |
-|---|---|---|
-| `Ask::Agent::Session` | session.rb | Full agent loop — message → tool calls → results → follow-up |
-| `Ask::Agent::Loop` | loop.rb | Turn management, loop detection, max-turn guard |
-| `Ask::Agent::ToolExecutor` | tool_executor.rb | Parallel/sequential tool execution with retry and abort |
-| `Ask::Agent::Compactor` | compactor.rb | Context window management with proactive/overflow compaction |
-| `Ask::Agent::Hooks` | hooks.rb | Before/after tool lifecycle callbacks |
-| `Ask::Agent::Events` | events.rb | Data.define event types for streaming and monitoring |
-| `Ask::Agent::Telemetry` | telemetry.rb | File-backed telemetry for error tracking |
-| `Ask::Agent::Reflector` | reflector.rb | Assistant response self-evaluation |
-| `Ask::Agent::MetaAgent` | meta_agent.rb | LLM-powered self-improvement from telemetry |
-| `Ask::Agent::Evaluator` | evaluator.rb | Independent response evaluation with structured rubric — different model, isolated context |
-| `Ask::Agent::Configuration` | configuration.rb | Global config: model, turns, concurrency, evaluator |
-
-## Evaluator
-
-Independent response evaluation with generator/evaluator separation. The
-evaluator uses a **separate model** (different from the session's model) and an
-**isolated context** to judge the agent's output — preventing the anti-pattern
-of a model grading its own work.
-
-### Quick start
-
-```ruby
-session = Ask::Agent::Session.new(
-  model: "gpt-4o",
-  evaluator: { model: "claude-sonnet-4", goal: "Write an email validator" }
-)
-session.run("Write email validation")
-```
-
-### Verdicts
-
-| Verdict | Behavior |
-|---------|----------|
-| `:accept` | Output passes — falls through to reflection |
-| `:revise` | Evaluator provides feedback; session runs another turn with it injected |
-| `:block` | Output is fundamentally wrong — returns blocked message, emits `EvaluationBlocked` |
-
-### Configuration
-
-```ruby
-# Set a global default evaluator model
-Ask::Agent.configure do |c|
-  c.default_evaluator_model = "claude-sonnet-4"
-end
-
-# Then use evaluator: true to enable with the default
-session = Ask::Agent::Session.new(model: "gpt-4o", evaluator: true)
-```
-
-### Custom rubric
-
-```ruby
-evaluator = Ask::Agent::Evaluator.new(
-  model: "claude-sonnet-4",
-  rubric: [
-    Ask::Agent::Evaluator::Dimension.new(
-      name: "performance",
-      description: "Is the implementation efficient?",
-      weight: 2
-    )
-  ]
-)
-
-result = evaluator.evaluate(
-  goal: "Write an email validator",
-  response: agent_output
-)
-result.accept?  # => true/false
-result.scores   # => { performance: 2 }
-result.feedback # => "Add edge case for unicode characters"
-```
-
-### Events
-
-The evaluator emits its own events during evaluation:
-
-```ruby
-session.on_event do |event|
-  case event
-  when Ask::Agent::Events::EvaluationStart
-    puts "Evaluating against: #{event.dimensions.join(', ')}"
-  when Ask::Agent::Events::EvaluationDelta
-    print event.content
-  when Ask::Agent::Events::EvaluationEnd
-    puts "Decision: #{event.decision}"
-    puts "Scores: #{event.scores}"
-  when Ask::Agent::Events::EvaluationBlocked
-    puts "Blocked: #{event.feedback}"
-  end
-end
-```
-
-## Events
-
-Stream session execution in real-time:
+Stream execution in real time with events:
 
 ```ruby
 session.on_event do |event|
@@ -131,95 +30,17 @@ session.on_event do |event|
     print event.content
   when Ask::Agent::Events::ToolExecutionStart
     puts "\nRunning #{event.name}..."
-  when Ask::Agent::Events::ToolExecutionEnd
-    puts "  → #{event.duration_ms}ms #{event.is_error ? 'error' : 'ok'}"
   end
 end
 ```
 
-## Extensions
-
-Opt-in safety modules:
-
-- **Permissions** — Access control for tools. Supports named access modes (`:full_access`, `:read_only`, `:ask_before_changes`) or custom blocked-tool lists.
-- **RateLimiter** — Prevent runaway tool calls (configurable per-minute and per-turn limits)
-- **AuditLog** — Immutable, append-only log of every tool call
-
-```ruby
-extensions = [
-  Ask::Agent::Extensions::Permissions.new(mode: :read_only),
-  Ask::Agent::Extensions::RateLimiter.new(max_calls_per_minute: 30),
-  Ask::Agent::Extensions::AuditLog.new(path: "agent.log")
-]
-
-session = Ask::Agent::Session.new(
-  model: "gpt-4o",
-  tools: [...],
-  hooks: {
-    before_tool: extensions.map(&:method(:before_tool_call)),
-    after_tool: extensions.select { |e| e.respond_to?(:after_tool_call) }.map(&:method(:after_tool_call))
-  }
-)
-```
-
-## Middleware
-
-Wrapping LLM provider calls with cross-cutting behavior:
-
-- **RetryOnFailure** — Retry on rate limits and server errors with exponential backoff
-- **ModelFallback** — Switch to a fallback model+provider on transient errors
-- **LogCalls** — Log every LLM provider call
-- **DefaultSettings** — Inject default generation parameters
-
-```ruby
-Ask::Agent.configure do |c|
-  c.middleware.use :retry_on_failure, max_retries: 3
-  c.middleware.use :model_fallback, fallbacks: [
-    { model: "claude-sonnet-4",  provider: :anthropic },
-    { model: "gemini-2.0-flash", provider: :google }
-  ]
-  c.middleware.use :log_calls, logger: Rails.logger
-  c.middleware.use :default_settings, temperature: 0.7
-end
-```
-
-### ModelFallback
-
-When the primary LLM is overloaded or down, `ModelFallback` transparently switches to a backup model+provider. Credentials for each provider are resolved automatically.
-
-**Static fallbacks** — ordered list tried in sequence:
-```ruby
-c.middleware.use :model_fallback, fallbacks: [
-  { model: "claude-sonnet-4",  provider: :anthropic },
-  { model: "gemini-2.0-flash", provider: :google }
-]
-```
-
-**Dynamic fallbacks** — lambda that receives the error and request:
-```ruby
-c.middleware.use :model_fallback, fallbacks: ->(error, request) {
-  if request[:messages].sum { |m| m[:content].to_s.length } > 100_000
-    [{ model: "claude-sonnet-4", provider: :anthropic }]  # long-context
-  else
-    [{ model: "gpt-4o-mini", provider: :openai }]           # cheaper
-  end
-}
-```
+## Declarative Agents
 
-**Custom eligible errors** — by default rate limits, server errors, and service unavailable:
-```ruby
-c.middleware.use :model_fallback,
-  fallbacks: [{ model: "claude-sonnet-4", provider: :anthropic }],
-  eligible_errors: [Ask::RateLimitError, Ask::ServerError]
-```
-
-## Agents
-
-Declarative agents follow a file convention. Each agent lives in a
-directory under `agents/` (or `app/agents/` in Rails); the directory
-name is the agent name, the file `agent.rb` defines the agent as a
-`<Name>::Agent < Ask::Agent::Definition` subclass, and a sibling
-`instructions.md` is auto-loaded as the system prompt.
+Agents follow a file convention. Each agent lives in a directory under
+`agents/` (or `app/agents/` in Rails); the directory name is the agent name,
+the file `agent.rb` defines the agent as a `<Name>::Agent <
+Ask::Agent::Definition` subclass, and a sibling `instructions.md` is
+auto-loaded as the system prompt.
 
 ```
 agents/
@@ -246,10 +67,22 @@ agent = Ask::Agent.new("health_check")
 response = agent.run("Check server health")
 ```
 
-Shared tools for all agents go in `agents/shared/tools/`. Per-agent
-skills go in `agents/<name>/skills/`, shared skills in `agents/shared/skills/`.
+Shared tools for all agents go in `agents/shared/tools/`. Per-agent skills go
+in `agents/<name>/skills/`, shared skills in `agents/shared/skills/`.
+
+## Essential API
+
+| Entry point | Purpose |
+|---|---|
+| `Ask::Agent::Session.new(model:, tools: [], max_turns: 25, ...)` | Full agent loop: message, tool calls, results, follow-up |
+| `session.run(message)` | Run the loop for one message |
+| `session.on_event { \|e\| }` | Stream `Ask::Agent::Events` (text deltas, tool execution, evaluation) |
+| `Ask::Agent.new("name")` | Build a session from a declarative agent definition |
+| `Ask.chat(message)` | One-shot chat without instantiating a Session |
+| `Ask::Agent.configure { \|c\| ... }` | Global defaults: model, provider, turns, compactor, middleware |
+| `askr` | CLI: `askr run <agent> [prompt]`, `askr list`, `askr schedule`, `askr new`, `askr skills` |
 
-## Configuration
+### Configuration
 
 ```ruby
 Ask::Agent.configure do |c|
@@ -263,26 +96,23 @@ Ask::Agent.configure do |c|
 end
 ```
 
-`default_provider` pins which provider serves the default model when the
-model name doesn't uniquely identify one (for example, the same model id
-registered under multiple OpenAI-compatible providers). A `provider:`
-passed to `Session.new` or declared in an agent `Definition` always wins
-over the global default.
+`default_provider` pins which provider serves the default model when the model
+name doesn't uniquely identify one (for example, the same model id registered
+under multiple OpenAI-compatible providers). A `provider:` passed to
+`Session.new` or declared in an agent `Definition` always wins over the global
+default.
 
-## Persistence
+## Full documentation
 
-```ruby
-store = Ask::Agent::Persistence::InMemory.new
-session = Ask::Agent::Session.new(model: "gpt-4o", persistence: store)
-session.run("Hello")
-session.save  # persisted to store
-```
+The full ask-rb documentation lives at https://ask-rb.github.io/ask-docs.
+https://ask-rb.github.io/ask-docs/core/agent covers ask-agent in depth,
+including the evaluator, middleware, extensions, cost tracking, and
+persistence. API reference: https://ask-rb.github.io/ask-docs/reference/api.
 
 ## Development
 
-```bash
+bundle install
 bundle exec rake test
-```
 
 ## License
 

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/loop.rb

@@ -94,7 +94,7 @@ module Ask
         end
 
         if @consecutive_tool_turns >= @max_consecutive_tool_turns
-          summary = all_tool_results.map { |r| r[:message].to_s.truncate(80) }.first(2).join("; ")
+          summary = all_tool_results.map { |r| truncate(r[:message], 80) }.first(2).join("; ")
           return "Based on my investigation: #{summary}"
         end
 
@@ -137,6 +137,15 @@ module Ask
 
       private
 
+      # Truncate a string for summaries without depending on ActiveSupport's
+      # String#truncate (which is not loaded by a bare `require "ask-agent"`).
+      def truncate(text, length)
+        s = text.to_s
+        return s if s.length <= length
+
+        "#{s[0, length - 3]}..."
+      end
+
       def loop_detected?(results)
         return false if results.empty?
 

data/lib/ask/agent/session.rb

@@ -41,8 +41,8 @@ module Ask
 
         @telemetry = telemetry.is_a?(Telemetry) ? telemetry : Telemetry.new(enabled: !!telemetry)
 
-        @chat = build_chat(model, system_prompt, tools, **chat_options)
         @tools = resolve_tools(tools)
+        @chat = build_chat(model, system_prompt, @tools, **chat_options)
         @loop = Loop.new(max_turns: max_turns)
         @tool_executor = ToolExecutor.new(max_retries: max_tool_retries, parallel: parallel_tools)
         @compactor = compactor ? build_compactor(compactor) : nil
@@ -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/streaming.rb

@@ -82,6 +82,15 @@ module Ask
 
         private
 
+        # Truncate a string for telemetry without depending on ActiveSupport's
+        # String#truncate (which is not loaded by a bare `require "ask-agent"`).
+        def truncate(text, length)
+          s = text.to_s
+          return s if s.length <= length
+
+          "#{s[0, length - 3]}..."
+        end
+
         def run_with_block(session, prompt, mapping)
           errors = []
 
@@ -154,7 +163,7 @@ module Ask
           when Events::ToolExecutionStart
             { name: event.name, id: event.id, args: safe_args(event.arguments) }
           when Events::ToolExecutionUpdate
-            { id: event.id, partial_result: event.partial_result.to_s.truncate(200) }
+            { id: event.id, partial_result: truncate(event.partial_result, 200) }
           when Events::ToolExecutionEnd
             { name: event.name, id: event.id, duration_ms: event.duration_ms, is_error: event.is_error }
           when Events::SessionEnd

data/lib/ask/agent/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Agent
-    VERSION = "0.24.2"
+    VERSION = "0.25.2"
   end
 end

metadata

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