pocketrb 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 90af53988338c89d33687693fc1a57069e32851cc3c98ce9f3bd52b69b335af6
-  data.tar.gz: 4095da56b7bf3b918485e90191cb568eacd24dfdcf47bddc1845b9702ce4a547
+  metadata.gz: 68a01066f9fb0881bd483bfb372258a4b1e6cdb34190bbcf802e440450861358
+  data.tar.gz: a532a6d6f9728e1e8f26c38d70cefe9c7a3a4d929ce1075a761b90b2aaf09cf7
 SHA512:
-  metadata.gz: e2a1e6398ba744257c0cde3b288c64dcb331684a52fff7e68c43ca9d9640b1b3de8edda1536d5eb2819a91b2b127bc29caebe14dd5ba606450e609b86667cb2c
-  data.tar.gz: 5010acdbbf7916b1e33392783559568cd6b74b4dd1d26d1017ca144f9b705478e15466d92fe069b966bd8dfda7473d14d8af5a3a2ee07e4db6fe21d253b69312
+  metadata.gz: fdeddd1528bd184cd141ff5cf96d5ef55e2ec7ff9f08cc35beea9454839e24a0eba881b3d100ab8f6c8cac0c7f13205b74afe6fc121930fe157b7e454653cf5f
+  data.tar.gz: 272669607c727e6cbabe8fd9ee980ac895b037e7b924e19891b4906caf7c56b7f9f514259dc72cb6fd6cd66e9265cb45da946fa4fbe310a31ceaa2f9572b2763

data/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-11-10
+
+### Changed
+
+- Enhancement: Add `openai_compatible` provider for any OpenAI chat completions server (vLLM, llama.cpp, llamafile, LM Studio, Ollama), configured with `openai_compatible_base_url` and an optional `openai_compatible_api_key`
+- Enhancement: Add Ruby warning category opt-in to test helpers
+- Maintenance: Add `fugit` as a runtime dependency, so cron expressions work without installing it separately
+- Maintenance: Require Ruby 4.0+ (`required_ruby_version` was `>= 3.2.0`; Ruby 3.2 is EOL and CI tests only Ruby 4.0)
+- Maintenance: Document `@return [Boolean]` on predicate methods to satisfy yard-lint 1.13.0
+- Maintenance: Remove unused runtime dependencies `anthropic`, `pastel`, `tty-markdown` and `tty-prompt`, allow `json` 3.x (`web_fetch` converts a body without a charset to UTF-8, and tool-call arguments with a duplicate key keep the last value, as on json 2.x) and drop the duplicate `playwright-ruby-client` entry from the `Gemfile`
+- Maintenance: Remove the leftover `README_ANALYSIS.md`, the placeholder WhatsApp bridge link from the README and list all providers under `chat --provider`
+
+### Fixed
+
+- Fix: `pocketrb whatsapp` without the `websocket-client-simple` gem raises `Pocketrb::MissingDependencyError` (a `LoadError`) that says to add the gem, instead of a bare `LoadError` (#14)
+- Fix: Cron jobs with a cron expression run on that schedule instead of every minute when `fugit` was not installed
+- Fix: `web_fetch` replaces invalid bytes in the response body, so such a page no longer fails with `invalid byte sequence` (declared charset) or raises `JSON::GeneratorError` in the next provider request (no charset)
+- Fix: `Providers::OpenRouter#chat_stream` no longer raises `FrozenError` on the first streamed chunk
+- Fix: `InboundMessage#has_media?` returns `false` instead of `nil` when media is `nil`
+- Fix: Replace retired default models with `claude-sonnet-5-5` (Anthropic, config) and `anthropic/claude-sonnet-5.5` (OpenRouter)
+- Fix: `Providers::Anthropic` does not send `temperature` to models that reject it (Opus 4.7+, Sonnet 5+, Haiku 5+, Fable and Mythos, dated IDs included)
+- Fix: `Providers::Anthropic::MODELS` lists `claude-opus-5-5`, `claude-sonnet-5-5` and `claude-haiku-5-5` with their 1M context window, so compaction no longer triggers at 200K
+- Fix: `Providers::RubyLLMProvider` no longer crashes on every call: rewritten on `ruby_llm` 2.x (dependency now `~> 2.0`), sends the whole history (assistant and tool messages included) in one request per turn, passes tool definitions, returns tool calls to the agent loop and streams through `chat_stream`
+- Fix: `ClaudeCLI` model aliases report current model IDs; OpenRouter popular models drop IDs OpenRouter no longer serves
+
+## [0.2.0] - 2026-03-30
+
+### Added
+
+- Rolling summaries in context compaction — prior summary is preserved and incorporated into new summaries across compaction cycles, preventing progressive context loss
+- Pressure-based compaction thresholds — compaction triggers when estimated tokens exceed a configurable percentage of the model's context window (`context_pressure`, default 70%)
+- Background (non-blocking) compaction via `schedule_compaction` with mutex-based thread safety and `wait_for_compaction` for clean shutdown
+- Compaction callbacks (`on_compact`) — fires after successful compaction with summary text and compacted message count
+- Separate compaction model configuration (`compaction_model` config key, `POCKETRB_COMPACTION_MODEL` env var) to use a cheaper/faster model for summaries
+- `context_pressure` configuration (`compaction_pressure` config key, `POCKETRB_COMPACTION_PRESSURE` env var)
+- `Providers::Base#context_window` method (default 200K); `Providers::Anthropic` overrides using MODELS hash
+
 ## [0.1.0] - 2026-02-04
 
 ### Added

data/README.md

@@ -9,13 +9,15 @@ A pocket-sized Ruby AI agent framework with multi-LLM support and advanced capab
 ## Features
 
 - **Clean async architecture**: MessageBus, proper tool_use API, async processing
-- **Multi-LLM support**: Claude (API + Max/OAuth), OpenRouter, OpenAI-compatible APIs, RubyLLM
+- **Multi-LLM support**: Claude (API + Max/OAuth + Proxy), OpenRouter, OpenAI-compatible APIs, RubyLLM, Claude CLI
 - **Multi-channel**: CLI, Telegram, WhatsApp (via bridge)
 - **Advanced features**: Planning system, context compaction, runtime skills system
 - **Simple memory**: JSON-based memory with keyword matching (no external dependencies)
 - **Media support**: Vision (images) via Claude, document handling
+- **Browser automation**: Headless Chromium with session management and advanced interactions
 - **Scheduling**: Cron jobs for automated tasks
 - **Personas**: Separate memory and identity from workspace for portable agent personalities
+- **Autonomous mode**: Skip permission prompts for sandboxed/container environments
 
 ## Installation
 
@@ -51,8 +53,8 @@ pocketrb chat [options]
 ```
 
 Options:
-- `-m, --model MODEL` - Model to use (default: claude-sonnet-4-20250514)
-- `-p, --provider PROVIDER` - LLM provider (anthropic, openrouter, ruby_llm)
+- `-m, --model MODEL` - Model to use (default: claude-sonnet-5-5)
+- `-p, --provider PROVIDER` - LLM provider (anthropic, openrouter, openai_compatible, ruby_llm, claude_cli, claude_max_proxy)
 - `-w, --workspace DIR` - Workspace directory for file access
 - `-M, --memory-dir DIR` - Memory/persona directory (default: same as workspace)
 - `-s, --system-prompt TEXT` - Custom system prompt
@@ -69,10 +71,16 @@ Options:
 - `-u, --allowed-users` - Restrict access to specific usernames/IDs
 - `-w, --workspace` - File access directory
 - `-M, --memory-dir` - Persona/memory directory
+- `--enable-cron` - Enable cron/scheduling service (default: true)
+- `--autonomous` - Skip permission prompts for sandboxed environments
 
 ### WhatsApp Bot
 
-Requires the [whatsapp-web.js bridge](https://github.com/user/whatsapp-bridge) running.
+Requires a whatsapp-web.js bridge running and the `websocket-client-simple` gem, which pocketrb does not install for you:
+
+```bash
+gem install websocket-client-simple   # or add gem "websocket-client-simple" to your Gemfile
+```
 
 ```bash
 pocketrb whatsapp --bridge-url ws://localhost:3001 --allowed-users +1234567890
@@ -150,7 +158,7 @@ Background knowledge the agent should always have access to.
 
 - **Name**: John
 - **Timezone**: UTC+1
-- **Preferences**: Prefers Python over JavaScript
+- **Preferences**: Prefers Ruby over JavaScript
 
 ## Project Context
 
@@ -213,6 +221,8 @@ Pocketrb includes several built-in skills:
 - **github** - GitHub CLI operations (`gh pr`, `gh issue`, etc.)
 - **tmux** - Tmux session management for isolated workspaces
 - **weather** - Weather forecasts via wttr.in
+- **proactive** - Proactive task management and suggestions
+- **reflection** - Self-reflection and learning from interactions
 
 ### Listing Skills
 
@@ -244,33 +254,42 @@ Create a skill called "deploy" that guides deployment to production
 | Tool | Description |
 |------|-------------|
 | `exec` | Execute shell commands (auto-backgrounds long commands) |
-| `spawn` | Spawn background subagents for parallel work |
+| `jobs` | Manage background jobs and check their status |
 
-### Web
+### Web & Browser
 
 | Tool | Description |
 |------|-------------|
 | `web_search` | Search the web (requires `BRAVE_API_KEY`) |
 | `web_fetch` | Fetch and extract content from URLs |
+| `browser_advanced` | Advanced browser automation with Chromium (screenshots, interactions, JavaScript) |
 
-### Planning & Memory
+### Memory & Knowledge
 
 | Tool | Description |
 |------|-------------|
 | `think` | Internal reasoning for complex problems |
-| `plan` | Create and manage multi-step execution plans |
-| `memory` | Store and search long-term memory |
+| `memory` | Store and search long-term memory (keyword-based) |
 
 ### Communication
 
 | Tool | Description |
 |------|-------------|
 | `message` | Send messages to channels (Telegram, WhatsApp) |
+| `send_file` | Send files (images, documents) to chat channels |
+
+### Scheduling
+
+| Tool | Description |
+|------|-------------|
+| `cron` | Schedule and manage recurring tasks |
 
 ## Providers
 
 ### Anthropic (default)
 
+Standard Anthropic API:
+
 ```bash
 export ANTHROPIC_API_KEY=sk-ant-...
 pocketrb chat --provider anthropic
@@ -278,20 +297,61 @@ pocketrb chat --provider anthropic
 
 ### Claude Max (OAuth)
 
-For Claude Max subscribers:
+For Claude Max subscribers using OAuth token:
 
 ```bash
 export ANTHROPIC_OAUTH_TOKEN=your-oauth-token
 pocketrb chat --provider anthropic
 ```
 
+### Claude Max Proxy
+
+Alternative Claude Max access via proxy:
+
+```bash
+pocketrb chat --provider claude_max_proxy
+```
+
+### Claude CLI
+
+Use the official Claude CLI (requires `claude` binary):
+
+```bash
+pocketrb chat --provider claude_cli
+```
+
 ### OpenRouter
 
 Access multiple models:
 
 ```bash
 export OPENROUTER_API_KEY=your-key
-pocketrb chat --provider openrouter --model anthropic/claude-sonnet-4
+pocketrb chat --provider openrouter --model anthropic/claude-sonnet-5.5
+```
+
+### OpenAI-compatible servers (local models)
+
+Any server with the OpenAI chat completions API: vLLM, llama.cpp server, llamafile, LM Studio, Ollama or OpenAI itself. Set the base URL (up to and including `/v1`) and the model name the server serves in `.pocketrb/config.yml`:
+
+```yaml
+provider: openai_compatible
+openai_compatible_base_url: http://localhost:8000/v1
+model: llama-3.1-8b-instruct
+# openai_compatible_api_key: your-key # only when the server requires one
+```
+
+```bash
+pocketrb chat --provider openai_compatible
+```
+
+Without `openai_compatible_api_key`, no `Authorization` header is sent.
+
+### RubyLLM
+
+Route requests through the [ruby_llm](https://rubyllm.com) gem (2.x). Models are resolved from its registry; set `anthropic_api_key` and/or `openai_api_key` for the providers you use:
+
+```bash
+pocketrb chat --provider ruby_llm --model claude-sonnet-5-5
 ```
 
 ## Memory System
@@ -353,15 +413,32 @@ pocketrb cron remove job_id
 
 ## Gateway Mode
 
-Run all services together:
+Run all services together with full configuration:
 
 ```bash
 pocketrb gateway \
   --telegram-token "$TELEGRAM_BOT_TOKEN" \
   --telegram-users your_username \
-  --enable-cron
+  --whatsapp-bridge ws://localhost:3001 \
+  --whatsapp-users "+1234567890" \
+  --enable-cron \
+  --enable-heartbeat \
+  --heartbeat-interval 1800 \
+  --autonomous
 ```
 
+Options:
+- `-m, --model` - Model to use
+- `-p, --provider` - LLM provider
+- `--telegram-token` - Telegram bot token
+- `--telegram-users` - Allowed Telegram usernames/IDs
+- `--whatsapp-bridge` - WhatsApp bridge WebSocket URL (default: ws://localhost:3001)
+- `--whatsapp-users` - Allowed WhatsApp phone numbers
+- `--enable-cron` - Enable cron service (default: true)
+- `--enable-heartbeat` - Enable heartbeat service (default: true)
+- `--heartbeat-interval` - Heartbeat interval in seconds (default: 1800)
+- `--autonomous` - Skip permission prompts for sandboxed environments
+
 ## Context Compaction
 
 Long conversations are automatically summarized to save tokens:
@@ -379,7 +456,7 @@ Located at `workspace/.pocketrb/config.yml` or `~/.pocketrb/config.yml`:
 
 ```yaml
 provider: anthropic
-model: claude-sonnet-4-20250514
+model: claude-sonnet-5-5
 max_iterations: 50
 ```
 
@@ -387,7 +464,7 @@ max_iterations: 50
 
 ```bash
 pocketrb config show
-pocketrb config set model claude-opus-4-20250514
+pocketrb config set model claude-opus-5-5
 pocketrb config get model
 ```
 
@@ -398,11 +475,15 @@ pocketrb config get model
 | `ANTHROPIC_API_KEY` | Anthropic API key |
 | `ANTHROPIC_OAUTH_TOKEN` | Claude Max OAuth token |
 | `OPENROUTER_API_KEY` | OpenRouter API key |
+| `OPENAI_COMPATIBLE_BASE_URL` | Base URL for the `openai_compatible` provider |
+| `OPENAI_COMPATIBLE_API_KEY` | API key for the `openai_compatible` provider (optional) |
 | `BRAVE_API_KEY` | Brave Search API key (for web_search tool) |
 | `TELEGRAM_BOT_TOKEN` | Telegram bot token |
-| `POCKETRB_PROVIDER` | Default provider (anthropic, openrouter, ruby_llm, claude_cli) |
+| `POCKETRB_PROVIDER` | Default provider (anthropic, openrouter, openai_compatible, ruby_llm, claude_cli, claude_max_proxy) |
 | `POCKETRB_MODEL` | Default model |
 | `POCKETRB_LOG_LEVEL` | Log level (debug, info, warn, error) |
+| `POCKETRB_AUTONOMOUS` | Enable autonomous mode (1, true) - skips permission prompts |
+| `POCKETRB_MAX_ITERATIONS` | Maximum agent loop iterations |
 
 ## Architecture
 

data/lib/pocketrb/agent/compaction.rb

@@ -8,6 +8,7 @@ module Pocketrb
       DEFAULT_MESSAGE_THRESHOLD = 40      # Compact when exceeding this many messages
       DEFAULT_TOKEN_THRESHOLD = 50_000    # Compact when exceeding this many estimated tokens
       DEFAULT_KEEP_RECENT = 15            # Keep this many recent messages uncompacted
+      DEFAULT_CONTEXT_PRESSURE = 0.7      # Compact when estimated tokens exceed this fraction of context window
       CHARS_PER_TOKEN = 4                 # Rough estimate for token counting
 
       COMPACTION_PROMPT = <<~PROMPT
@@ -17,18 +18,50 @@ module Pocketrb
         - Current task/goal if any
         - Any pending items or context needed for continuation
 
+        If a prior conversation summary is provided, incorporate its key points into your new summary
+        so that important context is preserved across compaction cycles.
+
         Keep the summary under 500 words. Focus on information the assistant needs to continue effectively.
       PROMPT
 
-      attr_reader :provider, :model
+      attr_reader :provider, :model, :context_window, :context_pressure, :on_compact
       attr_accessor :message_threshold, :token_threshold, :keep_recent
 
-      def initialize(provider:, model: nil, message_threshold: nil, token_threshold: nil, keep_recent: nil)
+      # Initialize a new compaction instance
+      # @param provider [Object] LLM provider instance for generating summaries
+      # @param model [String, nil] Model name to use for summarization (defaults to provider default)
+      # @param message_threshold [Integer, nil] Maximum messages before compaction (defaults to
+      #   DEFAULT_MESSAGE_THRESHOLD)
+      # @param token_threshold [Integer, nil] Maximum estimated tokens before compaction (defaults to
+      #   DEFAULT_TOKEN_THRESHOLD)
+      # @param keep_recent [Integer, nil] Number of recent messages to keep uncompacted (defaults to
+      #   DEFAULT_KEEP_RECENT)
+      # @param context_window [Integer, nil] Model context window size in tokens (defaults to provider value)
+      # @param context_pressure [Float, nil] Fraction of context window that triggers compaction (defaults to
+      #   DEFAULT_CONTEXT_PRESSURE)
+      # @param on_compact [Proc, nil] Callback called after compaction with (summary, compacted_count)
+      def initialize(
+        provider:,
+        model: nil,
+        message_threshold: nil,
+        token_threshold: nil,
+        keep_recent: nil,
+        context_window: nil,
+        context_pressure: nil,
+        on_compact: nil
+      )
         @provider = provider
         @model = model || provider.default_model
         @message_threshold = message_threshold || DEFAULT_MESSAGE_THRESHOLD
         @token_threshold = token_threshold || DEFAULT_TOKEN_THRESHOLD
         @keep_recent = keep_recent || DEFAULT_KEEP_RECENT
+        @context_window = context_window || provider.context_window(model: @model)
+        validate_context_window!(@context_window)
+        @context_pressure = context_pressure || DEFAULT_CONTEXT_PRESSURE
+        validate_context_pressure!(@context_pressure)
+        @on_compact = on_compact
+        @compact_mutex = Mutex.new
+        @compacting = false
       end
 
       # Check if compaction is needed for messages
@@ -36,8 +69,13 @@ module Pocketrb
       # @return [Boolean]
       def needs_compaction?(messages)
         return false if messages.size <= @keep_recent
+        return true if messages.size > @message_threshold
+
+        estimated = estimate_tokens(messages)
+        return true if estimated > @token_threshold
 
-        messages.size > @message_threshold || estimate_tokens(messages) > @token_threshold
+        # Pressure-based: trigger when estimated tokens exceed configured fraction of context window
+        estimated > @context_window * @context_pressure
       end
 
       # Compact messages by summarizing older ones
@@ -49,46 +87,92 @@ module Pocketrb
         # Split messages: older ones to summarize, recent ones to keep
         split_point = [messages.size - @keep_recent, 0].max
         to_summarize = messages[0...split_point]
-        to_keep = messages[split_point..]
 
         return messages if to_summarize.empty?
 
+        # Adjust split point to keep tool_use/tool_result pairs together
+        split_point = adjust_split_for_tool_pairs(messages, split_point)
+        to_summarize = messages[0...split_point]
+        to_keep = messages[split_point..]
+
+        # Extract prior summary for rolling context preservation
+        prior_summary = extract_prior_summary(to_summarize)
+
+        # Exclude the prior summary message from to_summarize to avoid duplication
+        to_summarize = to_summarize[1..] if prior_summary && !to_summarize.empty?
+
         Pocketrb.logger.info("Compacting #{to_summarize.size} messages into summary")
 
-        # Generate summary
-        summary = generate_summary(to_summarize)
+        # Generate summary (incorporating prior summary if present)
+        summary = generate_summary(to_summarize, prior_summary: prior_summary)
+        compacted_count = to_summarize.size
 
         # Build compacted message list
         compacted = []
         compacted << build_summary_message(summary)
         compacted.concat(to_keep)
 
+        @on_compact&.call(summary, compacted_count)
+
         compacted
       end
 
-      # Compact a session's messages in place
-      # @param session [Session::Session] Session to compact
+      # Compact a session's messages in place (synchronous)
+      # @param session [Session::Session] Session object containing messages to be compacted
       # @return [Boolean] Whether compaction occurred
       def compact_session!(session)
-        messages = session.messages.dup
-        return false unless needs_compaction?(messages)
+        @compact_mutex.synchronize do
+          perform_session_compaction(session)
+        end
+      end
 
-        # Filter out system messages for compaction
-        user_assistant_messages = messages.reject { |m| m.role == Providers::Role::SYSTEM }
-        return false if user_assistant_messages.size <= @keep_recent
+      # Schedule asynchronous compaction in a background thread
+      # @param session [Session::Session] Session object containing messages to be compacted
+      # @return [Thread, nil] Background thread or nil if compaction not needed or already running
+      def schedule_compaction(session)
+        # Guard check-and-set under mutex to prevent concurrent scheduling
+        thread = @compact_mutex.synchronize do
+          return nil if @compacting
 
-        compacted = compact(user_assistant_messages)
+          messages = session.messages.dup
+          return nil unless needs_compaction?(messages)
 
-        # Update session
-        session.messages.clear
-        compacted.each { |m| session.messages << m }
+          @compacting = true
 
-        Pocketrb.logger.info("Session compacted: #{messages.size} -> #{compacted.size} messages")
-        true
+          Thread.new do
+            @compact_mutex.synchronize do
+              perform_session_compaction(session)
+            ensure
+              @compacting = false
+            end
+          end
+        end
+
+        @compact_thread = thread
+      end
+
+      # Whether background compaction is currently running
+      # @return [Boolean]
+      def compacting?
+        @compacting
+      end
+
+      # Wait for any in-progress background compaction to finish
+      # @param timeout [Integer, nil] Maximum seconds to wait (nil = wait forever)
+      # @return [Boolean] true if compaction finished, false if timed out
+      def wait_for_compaction(timeout: nil)
+        return true unless @compact_thread&.alive?
+
+        if timeout
+          @compact_thread.join(timeout) ? true : false
+        else
+          @compact_thread.join
+          true
+        end
       end
 
       # Estimate token count for messages
-      # @param messages [Array<Message>] Messages to count
+      # @param messages [Array<Message>] Array of messages to analyze for token count estimation
       # @return [Integer] Estimated tokens
       def estimate_tokens(messages)
         total_chars = messages.sum do |msg|
@@ -114,13 +198,130 @@ module Pocketrb
 
       private
 
-      def generate_summary(messages)
+      # Validate that the context window size is a positive number
+      # @param value [Numeric] context window size in tokens to validate
+      # @return [void]
+      def validate_context_window!(value)
+        return if value.is_a?(Numeric) && value.positive?
+
+        raise ArgumentError, "context_window must be a positive number (got #{value.inspect})"
+      end
+
+      # Validate that context pressure is a float between 0.0 and 1.0
+      # @param value [Numeric] context pressure ratio to validate
+      # @return [void]
+      def validate_context_pressure!(value)
+        return if value.is_a?(Numeric) && value >= 0.0 && value <= 1.0
+
+        raise ArgumentError, "context_pressure must be between 0.0 and 1.0 (got #{value.inspect})"
+      end
+
+      # Perform the actual session compaction (must be called under compaction mutex)
+      # @param session [Session::Session] whose messages will be summarized and replaced with compacted history
+      # @return [Boolean] Whether compaction occurred
+      def perform_session_compaction(session)
+        # Snapshot messages under session lock to avoid races with add_message
+        messages, user_assistant_messages = session.with_lock do
+          msgs = session.messages.dup
+          ua = msgs.reject { |m| m.role == Providers::Role::SYSTEM }
+          [msgs, ua]
+        end
+
+        return false unless needs_compaction?(messages)
+        return false if user_assistant_messages.size <= @keep_recent
+
+        compacted = compact(user_assistant_messages)
+
+        # Replace session messages under session lock
+        session.with_lock do
+          session.messages.clear
+          compacted.each { |m| session.messages << m }
+        end
+
+        Pocketrb.logger.info("Session compacted: #{messages.size} -> #{compacted.size} messages")
+        true
+      end
+
+      # Adjust split point to keep tool_use/tool_result pairs together. If a tool_result is in the kept messages, ensure
+      # its corresponding assistant message with tool_calls is also kept
+      # @param messages [Array<Message>] full conversation history including tool use/result pairs
+      # @param split_point [Integer] Initial split point
+      # @return [Integer] Adjusted split point
+      def adjust_split_for_tool_pairs(messages, split_point)
+        return split_point if split_point.zero?
+
+        to_keep = messages[split_point..]
+
+        # Find all tool results in the kept messages
+        tool_call_ids = to_keep
+                        .select { |m| m.role == Providers::Role::TOOL }
+                        .filter_map(&:tool_call_id)
+                        .compact
+
+        return split_point if tool_call_ids.empty?
+
+        # Find the earliest assistant message with matching tool_calls that needs to be kept
+        earliest_tool_use_index = nil
+
+        messages[0...split_point].each_with_index do |msg, idx|
+          next unless msg.role == Providers::Role::ASSISTANT && msg.tool_calls
+
+          # Check if any tool_calls match the tool_results we're keeping
+          matching_tools = msg.tool_calls.select { |tc| tool_call_ids.include?(tc.id) }
+          if matching_tools.any?
+            earliest_tool_use_index = idx
+            break
+          end
+        end
+
+        # Adjust split point to include the assistant message with tool_calls
+        if earliest_tool_use_index
+          Pocketrb.logger.debug(
+            "Adjusted split point from #{split_point} to #{earliest_tool_use_index} " \
+            "to keep tool_use/tool_result pairs together"
+          )
+          earliest_tool_use_index
+        else
+          split_point
+        end
+      end
+
+      # Extract prior summary text from messages if the first message is a summary
+      # @param messages [Array<Message>] conversation history where the first entry may contain a prior summary marker
+      # @return [String, nil] Prior summary text or nil
+      def extract_prior_summary(messages)
+        return nil if messages.empty?
+
+        first = messages[0]
+        content = first.content.to_s
+
+        # Strict detection: must start with the marker and contain the end marker
+        start_marker = "[Previous conversation summary]"
+        end_marker = "[End of summary"
+        return nil unless content.start_with?(start_marker) && content.include?(end_marker)
+
+        # Extract the summary text between markers
+        match = content.match(/\[Previous conversation summary\]\n(.*?)\n\[End of summary/m)
+        match ? match[1] : nil
+      end
+
+      # Use the LLM provider to produce a concise summary of the given messages
+      # @param messages [Array<Message>] older messages to be summarized
+      # @param prior_summary [String, nil] existing summary from a previous compaction cycle to incorporate
+      # @return [String] generated summary text
+      def generate_summary(messages, prior_summary: nil)
         # Format messages for summarization
         formatted = format_for_summary(messages)
 
+        user_content = "Conversation history to summarize:\n\n#{formatted}"
+
+        if prior_summary
+          user_content = "Prior summary from earlier conversation:\n#{prior_summary}\n\n#{user_content}"
+        end
+
         summary_request = [
           Providers::Message.system(COMPACTION_PROMPT),
-          Providers::Message.user("Conversation history to summarize:\n\n#{formatted}")
+          Providers::Message.user(user_content)
         ]
 
         response = @provider.chat(
@@ -136,6 +337,9 @@ module Pocketrb
         basic_summary(messages)
       end
 
+      # Format messages as role-prefixed text for the summarization prompt
+      # @param messages [Array<Message>] conversation messages to format
+      # @return [String] newline-separated formatted message text
       def format_for_summary(messages)
         messages.map do |msg|
           role = msg.role.capitalize
@@ -144,6 +348,9 @@ module Pocketrb
         end.join("\n\n")
       end
 
+      # Extract plain text from message content that may be a String or Array of content blocks
+      # @param content [String, Array<Hash, String>] raw message content to extract text from
+      # @return [String] concatenated text content
       def extract_text_content(content)
         if content.is_a?(Array)
           content.filter_map do |block|
@@ -158,12 +365,18 @@ module Pocketrb
         end
       end
 
+      # Wrap a summary string in a user message with conversation summary markers
+      # @param summary [String] compacted summary text to embed
+      # @return [Message] user message containing the bracketed summary
       def build_summary_message(summary)
         Providers::Message.user(
           "[Previous conversation summary]\n#{summary}\n[End of summary - continuing conversation]"
         )
       end
 
+      # Build a simple statistical summary without calling the LLM (fallback)
+      # @param messages [Array<Message>] conversation messages to summarize by counting roles and extracting topics
+      # @return [String] basic text summary with message counts and recent topics
       def basic_summary(messages)
         # Create a very basic summary without LLM
         user_count = messages.count { |m| m.role == Providers::Role::USER }