xeno 0.0.1 → 0.0.2

data/docs/configuration.md

@@ -0,0 +1,56 @@
+# Configuration reference
+
+Every knob on `Xeno.configure`. Standalone apps configure in `agent/agent.rb`;
+mounted apps use `config/initializers/xeno.rb`. The mechanics behind these knobs
+— claims, heartbeats, budget and compaction semantics — are documented in
+[runtime.md](runtime.md).
+
+```ruby
+Xeno.configure do |config|
+  config.max_steps = 20
+  config.turn_stale_after = 5.minutes
+end
+```
+
+## The turn loop
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `max_steps` | `20` | Per-turn model-call budget. |
+| `max_turn_attempts` | `5` | Attempts before a turn is declared poison and fails. |
+| `turn_stale_after` | `5.minutes` | A running turn with an older heartbeat is presumed dead and reclaimable. |
+| `heartbeat_interval` | a quarter of `turn_stale_after` | Heartbeat cadence during model calls and tool bodies. |
+
+## Budgets
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `max_input_tokens_per_session` | `nil` (unlimited) | Per-session input-token budget. |
+| `max_output_tokens_per_session` | `nil` (unlimited) | Per-session output-token budget. |
+
+Per-agent override in `agent.rb`: `limits input_tokens:, output_tokens:`
+(`false` disables an axis).
+
+## Compaction
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `compaction_threshold` | `0.9` | Fraction of the context window that triggers automatic compaction. `nil`/`false` disables it; manual stays available. |
+| `compaction_context_window` | `nil` | Fallback window (tokens) for models the registry doesn't know. `nil`: automatic compaction never triggers for them. |
+| `compaction_tail_turns` | `2` | Recent turns kept verbatim through a compaction. |
+
+## HTTP and streaming
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `authenticate` | `nil` | Fail-closed auth lambda: falsy return is a 401, truthy becomes the request principal. |
+| `stream_poll_interval` | `0.25` | Seconds between event-stream polls. |
+| `stream_catch_up_batch` | `500` | Max events per poll; bounds catch-up reads on long sessions. |
+| `stream_max_duration` | `nil` | Hard cap (seconds) on one stream connection. `nil`: until the session ends. |
+| `stream_shutdown_check` | `nil` | Lambda: "is the server shutting down?" — open streams close when true. `nil` detects Puma's graceful stop. |
+
+## Deploys
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `stopping_check` | `nil` | Lambda: "is the worker shutting down?" — probed between steps; a true return releases the claim and re-enqueues. `nil` asks the queue adapter. |

data/docs/runtime.md

@@ -9,9 +9,9 @@ how the durability machinery actually works. The README sells it; this explains
   `running | waiting | completed | failed`. Owns one transcript chat, the turn ledger,
   the event stream, and at most one `continuation_token` (channel-owned resume handle,
   unique among ACTIVE sessions). A session stays active indefinitely — turns finishing
-  never retire it; **`reset` is the only terminal transition in v0.1**, and it nulls
+  never retire it; **`reset` is the only terminal transition**, and it nulls
   the token (audit copy in `metadata`) so the same handle can start fresh. The
-  `failed` status and `session.failed` event are reserved (never produced in v0.1).
+  `failed` status and `session.failed` event are reserved (never produced today).
 - **Turn** (`xeno_turns`) — one user message (or several, when queued messages fold)
   and all work until the agent responds. One ActiveJob. Statuses:
   `pending | running | waiting | completed | failed | cancelled`.
@@ -37,8 +37,8 @@ claim! (CAS) → clean crash artifacts → loop:
 
 Rules inherited from the RubyLLM v2 investigation (each empirically verified):
 
-1. Never `complete` (unbounded) or `run_tools` (re-executes everything on retry). The
-   runner IS the loop.
+1. Never `complete` (a turn must bound its model calls) or `run_tools` (no approval
+   gate, no per-call action checkpoint). The runner IS the loop.
 2. A killed process leaves a blank assistant row (`before_message` persists it before
    the HTTP call) that makes `complete?` read true — trailing blank assistant rows are
    deleted on entry.

data/exe/xeno

@@ -28,7 +28,7 @@ when "new"
     gem "xeno"
     # RubyLLM v2 is unreleased and the published 1.16.0 gem is incompatible;
     # xeno is built against this exact commit. Drop the pin at RubyLLM v2 GA.
-    gem "ruby_llm", github: "crmne/ruby_llm", ref: "2aaddf96"
+    gem "ruby_llm", github: "crmne/ruby_llm", ref: "be80b6f1"
     # Loads .env at boot. Remove if you manage secrets another way.
     gem "dotenv"
     gem "puma"

data/lib/generators/xeno/install/install_generator.rb

@@ -1,7 +1,8 @@
+# frozen_string_literal: true
+
 module Xeno
   module Generators
-    # Mounted-mode install: initializer, engine mount, migrations, and the
-    # agent/ scaffold.
+    # Mounted-mode install: initializer, engine mount, migrations, and the agent/ scaffold.
     class InstallGenerator < Rails::Generators::Base
       source_root File.expand_path("templates", __dir__)
 

data/lib/generators/xeno/install/templates/agent.rb

@@ -1,4 +1,3 @@
 Xeno.agent do
-  # Any RubyLLM model id; provider options pass through.
-  # model "claude-sonnet-4-6"
+  # Any RubyLLM model id; provider options pass through. model "claude-sonnet-4-6"
 end

data/lib/generators/xeno/install/templates/initializer.rb

@@ -1,8 +1,7 @@
 Xeno.configure do |config|
-  # HTTP auth is FAIL-CLOSED: every endpoint (except health) returns 401
-  # until you set this. The lambda receives the request; return something
-  # falsy to reject, or a truthy value to accept — whatever you return
-  # becomes the session's principal (visible to tools and approval lambdas).
+  # HTTP auth is FAIL-CLOSED: every endpoint (except health) returns 401 until you set this. The
+  # lambda receives the request; return something falsy to reject, or a truthy value to accept —
+  # whatever you return becomes the session's principal (visible to tools and approval lambdas).
   #
   # config.authenticate = ->(request) do
   #   token = request.headers["Authorization"]&.delete_prefix("Bearer ")
@@ -11,10 +10,8 @@ Xeno.configure do |config|
   #   )
   # end
 
-  # Per-turn model-call budget (runaway protection).
-  # config.max_steps = 20
+  # Per-turn model-call budget (runaway protection). config.max_steps = 20
 
-  # How long a silent turn is presumed alive before another worker may
-  # reclaim it. Keep it above your slowest model call.
-  # config.turn_stale_after = 5.minutes
+  # How long a silent turn is presumed alive before another worker may reclaim it. Keep it above
+  # your slowest model call. config.turn_stale_after = 5.minutes
 end

data/lib/generators/xeno/tool/tool_generator.rb

@@ -1,7 +1,9 @@
+# frozen_string_literal: true
+
 module Xeno
   module Generators
-    # rails g xeno:tool GetWeather → agent/tools/get_weather.rb
-    # (the path supplies the runtime name: get_weather)
+    # rails g xeno:tool GetWeather → agent/tools/get_weather.rb (the path supplies the runtime name:
+    # get_weather)
     class ToolGenerator < Rails::Generators::NamedBase
       source_root File.expand_path("templates", __dir__)
 

data/lib/tasks/xeno_tasks.rake

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 namespace :xeno do
   desc "Print the resolved agent: config, instructions, tools, diagnostics"
   task info: :environment do

data/lib/xeno/agent_config.rb

@@ -1,6 +1,7 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The config DSL evaluated from agent/agent.rb. Optional — defaults apply
-  # when the file is absent.
+  # The config DSL evaluated from agent/agent.rb. Optional — defaults apply when the file is absent.
   #
   #   Xeno.agent do
   #     model "anthropic/claude-sonnet-5"
@@ -25,8 +26,8 @@ module Xeno
     #     limits input_tokens: 2_000_000, output_tokens: 200_000
     #   end
     #
-    # `false` disables an axis even when a global cap is set; an axis left
-    # out inherits the global `Xeno.config.max_*_tokens_per_session`.
+    # `false` disables an axis even when a global cap is set; an axis left out inherits the global
+    # `Xeno.config.max_*_tokens_per_session`.
     def limits(**caps)
       unless caps.empty?
         unknown = caps.keys - %i[input_tokens output_tokens]
@@ -37,16 +38,16 @@ module Xeno
       @limits
     end
 
-    # The effective cap for one axis: agent override first (false = off),
-    # then the global config. nil = unlimited.
+    # The effective cap for one axis: agent override first (false = off), then the global config.
+    # nil = unlimited.
     def token_limit(axis, global)
       return nil if @limits[axis] == false
 
       @limits.fetch(axis, nil) || global
     end
 
-    # DSL setter and reader in one: `model "id", **options` inside the block,
-    # `config.model` afterwards.
+    # DSL setter and reader in one: `model "id", **options` inside the block, `config.model`
+    # afterwards.
     def model(id = nil, **options)
       if id
         @model_id = id

data/lib/xeno/agent_definition.rb

@@ -1,8 +1,9 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The resolved agent: everything discovered under the app's agent/
-  # directory, plus diagnostics for anything misplaced or broken.
-  # Discovery never raises — a broken agent directory yields a definition
-  # whose diagnostics say exactly what is wrong (surfaced by `rake xeno:info`).
+  # The resolved agent: everything discovered under the app's agent/ directory, plus diagnostics for
+  # anything misplaced or broken. Discovery never raises — a broken agent directory yields a
+  # definition whose diagnostics say exactly what is wrong (surfaced by `rake xeno:info`).
   class AgentDefinition
     SLOT_DIRS = %w[tools skills channels schedules hooks lib].freeze
     TOOL_SLUG = /\A[a-z][a-z0-9_]*\z/
@@ -19,9 +20,9 @@ module Xeno
     attr_reader :root, :name, :config, :instructions, :dynamic_instructions,
                 :tools, :schedules, :channels, :hooks, :diagnostics
 
-    # Builds the definition for the app's agent root. `resolver` maps a tool
-    # file's camelized basename to its constant; the default asks Zeitwerk
-    # (via const_get on Xeno::Tools) and is only overridden in tests.
+    # Builds the definition for the app's agent root. `resolver` maps a tool file's camelized
+    # basename to its constant; the default asks Zeitwerk (via const_get on Xeno::Tools) and is only
+    # overridden in tests.
     def self.load(root, name:, resolver: nil)
       new(root: root, name: name, resolver: resolver).tap(&:discover)
     end
@@ -62,11 +63,9 @@ module Xeno
 
     def dynamic_instructions? = !@dynamic_instructions.nil?
 
-    # The system prompt for one turn: static markdown first, the dynamic
-    # block's return appended (resolved fresh at every turn stage with the
-    # session context — the current_user use case). A raising block never
-    # bricks the session: the turn proceeds on the static instructions and
-    # the failure is logged.
+    # The system prompt for one turn: static markdown first, then the dynamic block's return,
+    # resolved fresh at every turn stage with the session context. A raising block never bricks the
+    # session — the turn proceeds on the static instructions and the failure is logged.
     def instructions_for(session: nil)
       parts = [ instructions ]
       if @dynamic_instructions
@@ -116,9 +115,8 @@ module Xeno
       end
     end
 
-    # agent/instructions.rb — `Xeno.instructions do |context| ... end`,
-    # resolved at turn-stage time (context: session, principal) and appended
-    # to the static markdown.
+    # agent/instructions.rb — `Xeno.instructions do |context| ... end`, resolved at turn-stage time
+    # (context: session, principal) and appended to the static markdown.
     def load_dynamic_instructions
       file = root.join("instructions.rb")
       return unless file.file?
@@ -153,10 +151,9 @@ module Xeno
           next
         end
 
-        # Xeno::Tool required, not just RubyLLM::Tool: a plain RubyLLM
-        # subclass leaks a namespaced wire name (`xeno--tools--foo`) that
-        # misses the slug-keyed lookup, and it has no approval API — the
-        # gate would silently fail open.
+        # Xeno::Tool required, not just RubyLLM::Tool: a plain RubyLLM subclass leaks a namespaced
+        # wire name (`xeno--tools--foo`) that misses the slug-keyed lookup, and it has no approval
+        # API — the gate would silently fail open.
         unless klass.is_a?(Class) && klass < Xeno::Tool
           error "tools/#{file.basename}: Xeno::Tools::#{slug.camelize} must subclass Xeno::Tool " \
                 "(naming and the approval gate depend on it)"
@@ -171,9 +168,9 @@ module Xeno
       Xeno::Tools.const_get(slug.camelize)
     end
 
-    # agent/schedules/*.md — YAML frontmatter with a cron: line, body is the
-    # task prompt. Compiled to Solid Queue recurring entries by
-    # `rake xeno:schedules:sync`; never fired on cadence in development.
+    # agent/schedules/*.md — YAML frontmatter with a cron: line, body is the task prompt. Compiled
+    # to Solid Queue recurring entries by `rake xeno:schedules:sync`; never fired on cadence in
+    # development.
     def discover_schedules
       dir = root.join("schedules")
       return unless dir.directory?
@@ -202,9 +199,9 @@ module Xeno
       end
     end
 
-    # agent/channels/*.rb — DSL files (`Xeno.channel :slack do ... end`).
-    # Loading registers the channel globally; the definition records what
-    # each file declared for diagnostics and xeno:info.
+    # agent/channels/*.rb — DSL files (`Xeno.channel :slack do ... end`). Loading registers the
+    # channel globally; the definition records what each file declared for diagnostics and
+    # xeno:info.
     def discover_channels
       dir = root.join("channels")
       return unless dir.directory?
@@ -228,9 +225,9 @@ module Xeno
       end
     end
 
-    # agent/hooks/*.rb — observe-only handlers (`Xeno.hook "type" do … end`).
-    # One file may declare several; they merge across files. Handlers for
-    # unknown event types get a warning (typos never fire).
+    # agent/hooks/*.rb — observe-only handlers (`Xeno.hook "type" do … end`). One file may declare
+    # several; they merge across files. Handlers for unknown event types get a warning (typos never
+    # fire).
     def discover_hooks
       dir = root.join("hooks")
       return unless dir.directory?

data/lib/xeno/approval_context.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Xeno
   # What an approval lambda gets to look at.
   ApprovalContext = Struct.new(:session, :turn, :tool_name, :arguments, :principal, keyword_init: true)

data/lib/xeno/arguments.rb

@@ -1,15 +1,14 @@
+# frozen_string_literal: true
+
 module Xeno
-  # Models send JSON-typed arguments loosely — the first field run had
-  # llama sending "4200" (String) for an integer-typed parameter, which
-  # flowed into execute unchecked. Casts each argument per the tool's
-  # declared parameter type; anything uncoercible becomes a validation
-  # error the runner turns into an error tool result (the model retries
-  # with fixed arguments) — never an exception into execute.
-  module Arguments
+  # Casts each tool argument to its declared parameter type. Models send JSON-typed arguments
+  # loosely ("4200" for an integer parameter); an uncoercible value becomes a validation error the
+  # runner turns into an error tool result for the model to retry — never an exception into execute.
+  module Arguments # :nodoc:
     module_function
 
-    # Returns [coerced_arguments, errors]. Undeclared keys pass through
-    # untouched (schema-based tools declare nothing here).
+    # Returns [coerced_arguments, errors]. Undeclared keys pass through untouched (schema-based
+    # tools declare nothing here).
     def coerce(tool_class, arguments)
       declared = tool_class.respond_to?(:declared_parameters) ? tool_class.declared_parameters : {}
       return [ arguments, [] ] if declared.empty? || !arguments.is_a?(Hash)

data/lib/xeno/ask_question.rb

@@ -1,9 +1,9 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The one framework tool in v0.1. It has no executable body: the model
-  # calling it parks the turn with an input.requested event, and a human's
-  # answer is injected as the tool result on resume — the same mechanics as
-  # approvals. Registered on every chat (outside the Xeno::Tools namespace,
-  # which belongs to the app's agent/tools/).
+  # The built-in question tool. It has no executable body: the model calling it parks the turn, and
+  # a human's answer is injected as the tool result on resume — the same mechanics as approvals.
+  # Registered on every chat, outside the Xeno::Tools namespace that belongs to the app.
   class AskQuestion < Tool
     description "Ask the human a question and wait for their answer. " \
                 "Use when you need information or a decision only they can provide."

data/lib/xeno/channels/slack.rb

@@ -1,15 +1,14 @@
+# frozen_string_literal: true
+
 require "openssl"
 require "net/http"
 
 module Xeno
   module Channels
-    # The Slack channel: Events API webhook with constant-time signature
-    # verification, thread-scoped sessions (continuation token =
-    # "slack:<channel>:<thread_ts>"), replies posted at turn completion,
-    # and plain-text approvals ("approve"/"deny"/an answer) in the thread.
-    #
-    # v0.1 scope: mentions and DMs start sessions; thread replies continue
-    # them. Post-then-edit streaming and Block Kit buttons are v0.2.
+    # The Slack channel: Events API webhook with constant-time signature verification, thread-scoped
+    # sessions (continuation token = "slack:<channel>:<thread_ts>"), and plain-text approvals in the
+    # thread. Mentions and DMs start sessions; thread replies continue them. Post-then-edit
+    # streaming is opt-in (stream_replies); Block Kit buttons are not implemented.
     class Slack
       SIGNATURE_VERSION = "v0".freeze
       TIMESTAMP_TOLERANCE = 300 # seconds; replayed webhooks are rejected
@@ -40,9 +39,9 @@ module Xeno
         @api_base
       end
 
-      # Opt-in post-then-edit streaming: the reply posts on the first model
-      # delta and is edited (~1s cadence, rate-limit aware) until the final
-      # text lands. Off by default — replies post once at completion.
+      # Opt-in post-then-edit streaming: the reply posts on the first model delta and is edited (~1s
+      # cadence, rate-limit aware) until the final text lands. Off by default — replies post once at
+      # completion.
       def stream_replies(value = nil)
         @stream_replies = value unless value.nil?
         @stream_replies
@@ -82,8 +81,8 @@ module Xeno
         post_message(channel: channel_id, thread_ts: thread_ts, text: content.to_s)
       end
 
-      # One per content-bearing model reply when stream_replies is on: the
-      # runner pushes deltas, we post-then-edit in the thread.
+      # One per content-bearing model reply when stream_replies is on: the runner pushes deltas, we
+      # post-then-edit in the thread.
       def streamer_for(session)
         return nil unless stream_replies
 
@@ -119,12 +118,10 @@ module Xeno
         end
       end
 
-      # Post-then-edit delivery for ONE streaming model reply. The first
-      # content delta posts the thread message; later deltas edit it at most
-      # once per EDIT_INTERVAL; finish writes the durable final text. Rate
-      # limits defer the next edit (Retry-After); any hard failure turns
-      # streaming off for this reply — the completion post is the fallback,
-      # and the durable truth is rows either way.
+      # Post-then-edit delivery for one streaming reply: the first content delta posts the thread
+      # message, later deltas edit it at most once per EDIT_INTERVAL, finish writes the final text.
+      # Rate limits defer the next edit; a hard failure turns streaming off for this reply and the
+      # completion post is the fallback.
       class Streamer
         EDIT_INTERVAL = 1.0 # seconds — comfortably under chat.update's tier
 
@@ -147,8 +144,8 @@ module Xeno
           @ts.nil? ? start_message : edit_message(@buffer.dup)
         end
 
-        # Returns true when this streamer delivered the reply (the runner
-        # then skips the completion post); false hands delivery back.
+        # Returns true when this streamer delivered the reply (the runner then skips the completion
+        # post); false hands delivery back.
         def finish(final_text)
           return false if @ts.nil?
 
@@ -196,8 +193,8 @@ module Xeno
         end
       end
 
-      # One JSON POST to the Slack Web API; 429 becomes RateLimited (with
-      # Retry-After), any other failure raises Xeno::Error.
+      # One JSON POST to the Slack Web API; 429 becomes RateLimited (with Retry-After), any other
+      # failure raises Xeno::Error.
       def api_post(method, payload)
         uri = URI("#{api_base}/#{method}")
         request = Net::HTTP::Post.new(uri)
@@ -242,14 +239,13 @@ module Xeno
         end
       end
 
-      # A reply into a waiting thread resolves the FIRST pending input; an
-      # unrelated reply is HELD as the next message (never auto-deny, never
-      # a forced answer):
+      # A reply into a waiting thread resolves the first pending input;
+      # an unrelated reply is held as the next message — never an
+      # auto-deny, never a forced answer.
       # - approvals: approve/deny words resolve; anything else holds.
-      # - questions with choices: match by 1-based index ("2"), by label
-      #   (case-insensitive), or by exact option text; no match holds and
-      #   the question stays pending.
-      # - free-form questions (no choices): any text is the answer.
+      # - questions with choices: match by 1-based index, label, or exact
+      #   option text; no match holds.
+      # - free-form questions: any text is the answer.
       def continue_session(session, text, principal)
         pending = Action.joins(:turn)
                         .where(xeno_turns: { session_id: session.id }, status: "pending_approval")

data/lib/xeno/channels.rb

@@ -1,16 +1,17 @@
+# frozen_string_literal: true
+
 module Xeno
-  # The channel registry. A channel (a) normalizes platform input into user
-  # messages, (b) owns the session's continuation token, and (c) decides
-  # delivery of agent output. HTTP is built in; agent/channels/*.rb declare
-  # the rest via the DSL:
+  # The channel registry. A channel normalizes platform input into user messages, owns the session's
+  # continuation token, and decides delivery of agent output. HTTP is built in; agent/channels/*.rb
+  # declare the rest:
   #
   #   Xeno.channel :slack do
   #     signing_secret Rails.application.credentials.dig(:slack, :signing_secret)
   #     bot_token     Rails.application.credentials.dig(:slack, :bot_token)
   #   end
   #
-  # Delivery is a failable nicety: the durable truth lives in the transcript
-  # and event rows, so a failed post logs and moves on.
+  # Delivery is a failable nicety: the durable truth lives in the transcript and event rows, so a
+  # failed post logs and moves on.
   module Channels
     module_function
 
@@ -27,7 +28,7 @@ module Xeno
       when :slack
         Slack.new(&block)
       else
-        raise Xeno::Error, "unknown channel type: #{name} (v0.1 ships :slack; http is built in)"
+        raise Xeno::Error, "unknown channel type: #{name} (:slack is bundled; http is built in)"
       end
     end
 
@@ -47,8 +48,8 @@ module Xeno
       Rails.logger.warn("xeno: channel input-request delivery failed for session #{session.id}: #{e.class}: #{e.message}")
     end
 
-    # A per-reply delta sink (post-then-edit streaming) when the session's
-    # channel opts in; nil otherwise. Failable nicety like all delivery.
+    # A per-reply delta sink (post-then-edit streaming) when the session's channel opts in; nil
+    # otherwise. Failable nicety like all delivery.
     def streamer_for(session)
       channel = for_session(session)
       return nil unless channel.respond_to?(:streamer_for)

data/lib/xeno/compaction.rb

@@ -1,20 +1,12 @@
+# frozen_string_literal: true
+
 module Xeno
-  # Summarize-and-replace compaction, mixed into TurnRunner and executed as
-  # a claimed turn (kind: "compaction"). Riding the turn machinery buys the
-  # hard properties for free: the claim CAS makes it exclusive, session
-  # ordering queues it behind an active or parked turn, the heartbeat covers
-  # the summary model call, and a crash replays it (the applied result is
-  # recorded on the turn row, so replay never compacts twice).
+  # Summarize-and-replace compaction, run as a claimed turn (kind: "compaction") so it is exclusive,
+  # queues behind active work, and replays safely after a crash.
   #
-  # Shape: the system prompt survives untouched; the most recent
-  # `compaction_tail_turns` user-anchored turns survive verbatim (a tail cut
-  # at a user row can never separate an assistant's tool calls from their
-  # results); everything between is summarized by a throwaway model call
-  # (the active model, never persisted) and REPLACED — the summary is
-  # written into the earliest compacted row so both id- and created_at-
-  # ordering keep it in place, and the remaining rows are destroyed
-  # newest-first (results before the tool_calls they reference).
-  module Compaction
+  # The system prompt and the last `compaction_tail_turns` turns survive verbatim; everything before
+  # them is summarized by a throwaway model call and replaced in place.
+  module Compaction # :nodoc:
     SUMMARY_PREFIX = "[Conversation summary — earlier messages were compacted]".freeze
 
     COMPACTION_PROMPT = <<~PROMPT.freeze
@@ -50,8 +42,9 @@ module Xeno
       (turn.user_message || {}).key?("result")
     end
 
-    # Everything strictly before the tail is compactable. The tail starts at
-    # the Nth-from-last user row; with too few turns there is nothing to do.
+    # Everything strictly before the tail is compactable. The tail starts at the Nth-from-last user
+    # row — a cut at a user row never splits an assistant's tool calls from their results. With too
+    # few turns there is nothing to do.
     def compaction_plan(rows)
       system_rows, convo = rows.partition { |row| row.role == "system" }
       user_positions = convo.each_index.select { |i| convo[i].role == "user" }
@@ -65,9 +58,8 @@ module Xeno
       end
     end
 
-    # One model call on a throwaway chat — the active model with the agent's
-    # runtime options, no persistence, no tools. A previous summary (from an
-    # earlier compaction) is just an early row here and flows in whole.
+    # One model call on a throwaway chat: no persistence, no tools. An earlier compaction's summary
+    # is an ordinary early row here.
     def compaction_summary(rows)
       options = definition.config.model_options
       llm = RubyLLM.chat(
@@ -92,17 +84,16 @@ module Xeno
       }.join("\n\n")
     end
 
-    # The keeper (earliest compacted row) becomes the summary in place; the
-    # rest are destroyed newest-first. Rows, marker, and the
-    # compaction.completed event commit together — replay after any crash
-    # is a pure no-op past this transaction.
+    # The earliest compacted row becomes the summary in place; the rest are destroyed newest-first.
+    # Rows, marker, and event commit together, so replay after a crash is a no-op past this
+    # transaction.
     def apply_compaction!(plan, summary)
       keeper, *rest = plan[:compact]
 
       ActiveRecord::Base.transaction do
         rest.reverse_each(&:destroy!)
-        # A parent tool call on a surviving earlier row would otherwise
-        # dangle a result FK at the repurposed keeper.
+        # A parent tool call on a surviving earlier row would otherwise dangle a result FK at the
+        # repurposed keeper.
         keeper.ruby_llm_tool_calls.destroy_all
         keeper.ruby_llm_parent_tool_call&.update!(result: nil)
         keeper.update!(
@@ -123,10 +114,8 @@ module Xeno
       end
     end
 
-    # Between-turns trigger: after a message turn completes, stage a
-    # compaction turn when the last model call's context usage crossed the
-    # threshold share of the model's window (config fallback when the
-    # registry doesn't know the window).
+    # After a message turn completes, stage a compaction turn when the last model call crossed the
+    # threshold share of the model's window (config fallback when the registry doesn't know it).
     def maybe_stage_compaction
       threshold = Xeno.config.compaction_threshold
       return unless threshold
@@ -151,9 +140,7 @@ module Xeno
       window || Xeno.config.compaction_context_window
     end
 
-    # What the provider counted for the last completed call — the truthful
-    # "how full is the context" number, from the per-attempt usage ledger
-    # (message rows no longer carry token columns).
+    # The provider's count for the last completed call, read from the per-attempt usage ledger.
     def compaction_tokens_used
       last = @chat.ruby_llm_usages.where(operation: "chat", status: "succeeded")
                   .where.not(input_tokens: nil).order(:created_at, :id).last