anima-core 1.2.0 → 1.3.0

data/lib/analytical_brain/runner.rb

@@ -9,7 +9,9 @@ module AnalyticalBrain
   # active depends on the session type:
   #
   # * **Parent sessions** — session naming, skill/workflow/goal management
-  # * **Child sessions** — sub-agent nickname assignment, skill/workflow/goal management
+  # * **Child sessions** — sub-agent nickname assignment, skill management
+  #   (goal tracking and workflows disabled — sub-agents manage their sole goal
+  #   via mark_goal_completed)
   #
   # Tools mutate the observed session directly (e.g. renaming it, activating
   # skills), but no trace of the brain's reasoning is persisted — events are
@@ -51,7 +53,8 @@ module AnalyticalBrain
           ──────────────────────────────
           SKILL MANAGEMENT
           ──────────────────────────────
-          Activate skills when the conversation enters their domain.
+          Activate skills when the conversation signals intent — before the agent acts on it.
+          Late activation means the agent works without domain knowledge.
           Deactivate when the agent moves to a different domain.
           Multiple skills can be active at once.
         PROMPT
@@ -104,7 +107,7 @@ module AnalyticalBrain
 
     # Which responsibilities activate for each session type.
     PARENT_RESPONSIBILITIES = %i[session_naming skill_management workflow_management goal_tracking].freeze
-    CHILD_RESPONSIBILITIES = %i[sub_agent_naming skill_management workflow_management goal_tracking].freeze
+    CHILD_RESPONSIBILITIES = %i[sub_agent_naming skill_management].freeze
 
     # @param session [Session] the session to observe and maintain
     # @param client [LLM::Client, nil] injectable LLM client (defaults to fast model)
@@ -201,7 +204,7 @@ module AnalyticalBrain
         #{transcript}
         ```
 
-        Assign a nickname, activate relevant skills, then call everything_is_ready.
+        Assign a nickname and activate relevant skills, then call everything_is_ready.
       MSG
       [{role: "user", content: content}]
     end

data/lib/anima/cli/mcp/secrets.rb

@@ -5,8 +5,8 @@ require "thor"
 module Anima
   class CLI < Thor
     class Mcp < Thor
-      # CLI commands for managing MCP secrets stored in Rails encrypted
-      # credentials. Secrets are referenced in mcp.toml via
+      # CLI commands for managing MCP secrets stored in the encrypted
+      # secrets table. Secrets are referenced in mcp.toml via
       # +${credential:key_name}+ syntax.
       #
       # @example Store a secret
@@ -22,7 +22,7 @@ module Anima
           true
         end
 
-        desc "set KEY=VALUE", "Store an MCP secret in encrypted credentials"
+        desc "set KEY=VALUE", "Store an MCP secret in encrypted secrets"
         def set(pair)
           key, value = pair.split("=", 2)
           unless value
@@ -50,7 +50,7 @@ module Anima
           keys.each { |key| say "  #{key}" }
         end
 
-        desc "remove KEY", "Remove an MCP secret from encrypted credentials"
+        desc "remove KEY", "Remove an MCP secret from encrypted storage"
         def remove(key)
           secrets = require_mcp_secrets
           unless secrets.list.include?(key)

data/lib/anima/cli/mcp.rb

@@ -12,7 +12,7 @@ module Anima
         true
       end
 
-      desc "secrets SUBCOMMAND", "Manage MCP secrets in encrypted credentials"
+      desc "secrets SUBCOMMAND", "Manage MCP secrets in encrypted storage"
       subcommand "secrets", Secrets
 
       desc "list", "List configured MCP servers with health status"
@@ -40,14 +40,14 @@ module Anima
 
         Use -e KEY=VALUE to set environment variables (stdio servers).
         Use -H "Header: Value" to set HTTP headers (HTTP servers).
-        Use -s KEY=VALUE to store a secret in encrypted credentials.
+        Use -s KEY=VALUE to store a secret in encrypted storage.
       DESC
       option :env, aliases: "-e", type: :string, repeatable: true, banner: "KEY=VALUE",
         desc: "Environment variables (repeatable)"
       option :header, aliases: "-H", type: :string, repeatable: true, banner: "Header: Value",
         desc: "HTTP headers (repeatable)"
       option :secret, aliases: "-s", type: :string, repeatable: true, banner: "KEY=VALUE",
-        desc: "Store secret in encrypted credentials (repeatable)"
+        desc: "Store secret in encrypted storage (repeatable)"
       def add(name, *rest)
         if rest.empty?
           say "Error: missing server URL or command.", :red
@@ -87,7 +87,7 @@ module Anima
         ::Mcp::Config.new
       end
 
-      # Stores secrets from -s KEY=VALUE flags in encrypted credentials.
+      # Stores secrets from -s KEY=VALUE flags in the encrypted secrets table.
       def store_secrets(secret_strings)
         return unless secret_strings&.any?
 

data/lib/anima/installer.rb

@@ -117,7 +117,13 @@ module Anima
           raise_if_missing_key: true
         )
 
-        config.write("secret_key_base: #{SecureRandom.hex(64)}\n")
+        config.write(<<~YAML)
+          secret_key_base: #{SecureRandom.hex(64)}
+          active_record_encryption:
+            primary_key: #{SecureRandom.base64(32)}
+            deterministic_key: #{SecureRandom.base64(32)}
+            key_derivation_salt: #{SecureRandom.base64(32)}
+        YAML
         File.chmod(0o600, content_str)
         say "  created credentials for #{env}"
       end

data/lib/anima/settings.rb

@@ -91,6 +91,11 @@ module Anima
       # @return [Integer]
       def token_budget = get("llm", "token_budget")
 
+      # Maximum character length for the Think tool's thoughts parameter.
+      # Sub-agents receive half this budget (their tasks are less complex).
+      # @return [Integer]
+      def thinking_budget = get("llm", "thinking_budget")
+
       # ─── Timeouts (seconds) ────────────────────────────────────────
 
       # LLM API request timeout.
@@ -114,6 +119,13 @@ module Anima
       # @return [Integer] seconds
       def tool_timeout = get("timeouts", "tool")
 
+      # Polling interval for user interrupt checks during long-running commands.
+      # Enforces a 0.5s floor to prevent busy-polling from misconfiguration.
+      # @return [Numeric] seconds (minimum 0.5)
+      def interrupt_check_interval
+        [get("timeouts", "interrupt_check"), 0.5].max
+      end
+
       # ─── Shell ──────────────────────────────────────────────────────
 
       # Maximum bytes of command output before truncation.
@@ -126,11 +138,11 @@ module Anima
       # @return [Integer]
       def max_file_size = get("tools", "max_file_size")
 
-      # Maximum lines returned by the read tool.
+      # Maximum lines returned by the read_file tool.
       # @return [Integer]
       def max_read_lines = get("tools", "max_read_lines")
 
-      # Maximum bytes returned by the read tool.
+      # Maximum bytes returned by the read_file tool.
       # @return [Integer]
       def max_read_bytes = get("tools", "max_read_bytes")
 
@@ -142,6 +154,16 @@ module Anima
       # @return [Integer]
       def min_web_content_chars = get("tools", "min_web_content_chars")
 
+      # Maximum characters of tool output before head+tail truncation.
+      # Full output saved to a temp file for paginated reading.
+      # @return [Integer]
+      def max_tool_response_chars = get("tools", "max_tool_response_chars")
+
+      # Maximum characters of sub-agent result before head+tail truncation.
+      # Higher than tool threshold because sub-agent output is already curated.
+      # @return [Integer]
+      def max_subagent_response_chars = get("tools", "max_subagent_response_chars")
+
       # ─── Session ────────────────────────────────────────────────────
 
       # View mode applied to new sessions: "basic", "verbose", or "debug".
@@ -206,6 +228,13 @@ module Anima
       # @return [Integer]
       def analytical_brain_message_window = get("analytical_brain", "message_window")
 
+      # ─── Goals ──────────────────────────────────────────────────────
+
+      # Number of meaningful messages (user + agent turns) after completion
+      # before a completed goal is automatically evicted from context.
+      # @return [Integer]
+      def completed_decay_messages = get("goals", "completed_decay_messages")
+
       # ─── Mneme (Memory Department) ────────────────────────────────
 
       # Maximum tokens per Mneme LLM response.

data/lib/anima/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Anima
-  VERSION = "1.2.0"
+  VERSION = "1.3.0"
 end

data/lib/anima.rb

@@ -12,7 +12,7 @@ module Anima
   end
 
   # Boots Rails when CLI commands need access to Rails-managed resources
-  # like encrypted credentials. No-op if Rails is already loaded.
+  # like the encrypted secrets table. No-op if Rails is already loaded.
   def self.boot_rails!
     return if defined?(Rails)
 

data/lib/credential_store.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-# Low-level read/write operations on Rails encrypted credentials.
-# Wraps the merge-and-write pattern used by {SessionChannel#write_anthropic_token}
-# in a reusable helper. All namespacing (e.g. +mcp+, +anthropic+) is the
-# caller's responsibility — this class operates on raw top-level keys.
+# Read/write operations for runtime secrets (API tokens, MCP credentials).
+# Backed by the {Secret} model with Active Record Encryption — values are
+# encrypted at rest and always fresh (no caching, no file-path issues in
+# forked Solid Queue workers).
+#
+# All namespacing (e.g. +mcp+, +anthropic+) is the caller's responsibility.
 #
 # @example Writing a nested credential
 #   CredentialStore.write("mcp", "linear_api_key" => "sk-xxx")
@@ -13,91 +15,40 @@
 class CredentialStore
   class << self
     # Writes one or more key-value pairs under a top-level namespace.
-    # Merges into existing credentials, preserving sibling keys.
+    # Upserts: existing keys are updated, new keys are created.
     #
-    # @param namespace [String] top-level YAML key (e.g. "mcp", "anthropic")
+    # @param namespace [String] top-level grouping key (e.g. "mcp", "anthropic")
     # @param pairs [Hash<String, String>] key-value pairs to store
     # @return [void]
     def write(namespace, pairs)
-      existing = load_credentials
-      section = existing[namespace] ||= {}
-      section.merge!(pairs)
-      save_credentials(existing)
+      Secret.write(namespace, pairs)
     end
 
     # Reads a single credential value from a namespace.
-    # Busts the Rails credentials cache first so cross-process writes
-    # (e.g. token saved in the web process, read in the SolidQueue worker)
-    # are always visible.
     #
-    # @param namespace [String] top-level YAML key
+    # @param namespace [String] top-level grouping key
     # @param key [String] credential key within the namespace
     # @return [String, nil] credential value or nil if not found
     def read(namespace, key)
-      bust_credentials_cache!
-      Rails.application.credentials.dig(namespace.to_sym, key.to_sym)
+      Secret.read(namespace, key)
     end
 
-    # Lists all keys under a namespace.
+    # Lists all keys under a namespace (not values).
     #
-    # @param namespace [String] top-level YAML key
-    # @return [Array<String>] credential keys (not values)
+    # @param namespace [String] top-level grouping key
+    # @return [Array<String>] credential keys
     def list(namespace)
-      section = Rails.application.credentials.dig(namespace.to_sym)
-      return [] unless section.is_a?(Hash)
-
-      section.keys.map(&:to_s)
+      Secret.list(namespace)
     end
 
     # Removes a single key from a namespace.
     # No-op if the key does not exist.
     #
-    # @param namespace [String] top-level YAML key
+    # @param namespace [String] top-level grouping key
     # @param key [String] credential key to remove
     # @return [void]
     def remove(namespace, key)
-      existing = load_credentials
-      section = existing[namespace]
-      return unless section.is_a?(Hash)
-      return unless section.key?(key)
-
-      section.delete(key)
-      existing.delete(namespace) if section.empty?
-      save_credentials(existing)
-    end
-
-    private
-
-    # Reads and parses the raw YAML from encrypted credentials.
-    # Returns an empty hash when the credentials file does not exist yet.
-    #
-    # @return [Hash] parsed credentials
-    def load_credentials
-      creds = Rails.application.credentials
-      YAML.safe_load(creds.read) || {}
-    rescue ActiveSupport::EncryptedFile::MissingContentError
-      {}
-    end
-
-    # Writes the full credentials hash back to the encrypted file and
-    # invalidates the Rails memoization cache so subsequent reads see
-    # fresh data.
-    #
-    # @param data [Hash] complete credentials hash to persist
-    # @return [void]
-    def save_credentials(data)
-      creds = Rails.application.credentials
-      creds.write(data.to_yaml)
-      bust_credentials_cache!
-    end
-
-    # Clears the Rails credentials in-memory cache so the next access
-    # re-reads and decrypts from disk. Required because Rails memoizes
-    # the decrypted config in @config per-process.
-    #
-    # @return [void]
-    def bust_credentials_cache!
-      Rails.application.credentials.instance_variable_set(:@config, nil)
+      Secret.remove(namespace, key)
     end
   end
 end

data/lib/events/base.rb

@@ -16,7 +16,7 @@ module Events
     def initialize(content:, session_id: nil)
       @content = content
       @session_id = session_id
-      @timestamp = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+      @timestamp = Time.current.to_ns
     end
 
     # @return [String] event type identifier

data/lib/events/subscribers/persister.rb

@@ -9,6 +9,11 @@ module Events
     # session. When initialized without one (global mode), the session is
     # looked up from the event's session_id payload field.
     #
+    # User messages are NOT persisted here — they are created directly by
+    # their callers ({SessionChannel#speak}, {AgentLoop#run}) so the
+    # message ID is available for bounce-back cleanup. Pending user
+    # messages live in the {PendingMessage} table, outside the event bus.
+    #
     # @example Session-scoped
     #   persister = Events::Subscribers::Persister.new(session)
     #   Events::Bus.subscribe(persister)
@@ -28,10 +33,10 @@ module Events
 
       # Receives a Rails.event notification hash and persists it.
       #
-      # Skips non-pending user messages — those are persisted by their
-      # callers ({SessionChannel#speak} for idle sessions,
-      # {AgentLoop#process} for direct usage). Also skips event types
-      # not in {Message::TYPES} (transient events like {Events::BounceBack}).
+      # Skips user messages — those are persisted by their callers
+      # ({SessionChannel#speak}, {AgentLoop#run}). Also skips event
+      # types not in {Message::TYPES} (transient events like
+      # {Events::BounceBack}).
       #
       # @param event [Hash] with :payload containing event data
       def emit(event)
@@ -41,7 +46,7 @@ module Events
         event_type = payload[:type]
         return if event_type.nil?
         return unless Message::TYPES.include?(event_type)
-        return if persisted_by_job?(event_type, payload)
+        return if event_type == "user_message"
 
         target_session = @session || Session.find_by(id: payload[:session_id])
         return unless target_session
@@ -50,9 +55,8 @@ module Events
           target_session.messages.create!(
             message_type: event_type,
             payload: payload,
-            status: payload[:status],
             tool_use_id: payload[:tool_use_id],
-            timestamp: payload[:timestamp] || Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+            timestamp: payload[:timestamp] || Time.current.to_ns
           )
         end
       end
@@ -60,17 +64,6 @@ module Events
       def session=(new_session)
         @mutex.synchronize { @session = new_session }
       end
-
-      private
-
-      # Non-pending user messages are persisted by their callers
-      # ({SessionChannel#speak}, {AgentLoop#process}) so the message ID
-      # is available for bounce-back cleanup if LLM delivery fails.
-      # Pending messages are still auto-persisted here because they
-      # queue while the session is busy.
-      def persisted_by_job?(event_type, payload)
-        event_type == "user_message" && payload[:status] != Message::PENDING_STATUS
-      end
     end
   end
 end

data/lib/events/subscribers/subagent_message_router.rb

@@ -14,7 +14,8 @@ module Events
     #
     # **Parent → Child:** When a parent agent emits an {Events::AgentMessage}
     # containing `@name` mentions, the router persists the message in each
-    # matching child session and wakes them via {AgentRequestJob}.
+    # matching child session with a +[from parent]:+ origin label and wakes
+    # them via {AgentRequestJob}.
     #
     # Both directions delegate to {Session#enqueue_user_message}, which
     # respects the target session's processing state — persisting directly
@@ -25,9 +26,12 @@ module Events
     class SubagentMessageRouter
       include Events::Subscriber
 
-      # Attribution prefix format for messages routed from child to parent.
-      # @example "[sub-agent @loop-sleuth]: Here's what I found..."
-      ATTRIBUTION_FORMAT = "[sub-agent @%s]: %s"
+      # @see Tools::ResponseTruncator::ATTRIBUTION_FORMAT
+      ATTRIBUTION_FORMAT = Tools::ResponseTruncator::ATTRIBUTION_FORMAT
+
+      # Origin label for messages routed from parent agent to sub-agent.
+      # Lets the sub-agent distinguish delegated work from direct user input.
+      PARENT_ATTRIBUTION_FORMAT = "[from parent]: %s"
 
       # Regex to extract @mention names from parent agent messages.
       MENTION_PATTERN = /@(\w[\w-]*)/
@@ -64,7 +68,8 @@ module Events
       private
 
       # Forwards a sub-agent's text message to its parent session
-      # via {Session#enqueue_user_message}.
+      # via {Session#enqueue_user_message}. Truncates oversized messages
+      # to protect the parent's context window.
       #
       # @param child [Session] the sub-agent session
       # @param content [String] the sub-agent's message text
@@ -73,13 +78,18 @@ module Events
         return unless parent
 
         name = child.name || "agent-#{child.id}"
-        attributed = format(ATTRIBUTION_FORMAT, name, content)
+        truncated = Tools::ResponseTruncator.truncate(
+          content,
+          threshold: Anima::Settings.max_subagent_response_chars,
+          reason: "sub-agent output displays first/last #{Tools::ResponseTruncator::HEAD_LINES} lines"
+        )
+        attributed = format(ATTRIBUTION_FORMAT, name, truncated)
 
         parent.enqueue_user_message(attributed)
       end
 
       # Scans a parent agent's message for @mentions and routes the message
-      # to each mentioned child session.
+      # to each mentioned child session with origin attribution.
       #
       # @param parent [Session] the parent session
       # @param content [String] the parent agent's message text
@@ -90,11 +100,13 @@ module Events
         active_children = parent.child_sessions.where.not(name: nil).index_by(&:name)
         return if active_children.empty?
 
+        attributed = format(PARENT_ATTRIBUTION_FORMAT, content)
+
         mentioned_names.each do |name|
           child = active_children[name]
           next unless child
 
-          child.enqueue_user_message(content)
+          child.enqueue_user_message(attributed)
         end
       end
     end

data/lib/events/user_message.rb

@@ -4,25 +4,14 @@ module Events
   class UserMessage < Base
     TYPE = "user_message"
 
-    # @return [String, nil] "pending" when queued during active processing, nil otherwise
-    attr_reader :status
-
     # @param content [String] message text
     # @param session_id [Integer, nil] session identifier
-    # @param status [String, nil] "pending" when queued during active agent processing
-    def initialize(content:, session_id: nil, status: nil)
-      super(content: content, session_id: session_id)
-      @status = status
+    def initialize(content:, session_id: nil)
+      super
     end
 
     def type
       TYPE
     end
-
-    def to_h
-      h = super
-      h[:status] = status if status
-      h
-    end
   end
 end

data/lib/llm/client.rb

@@ -15,8 +15,8 @@ module LLM
   #   registry.register(Tools::WebGet)
   #   client.chat_with_tools(messages, registry: registry, session_id: session.id)
   class Client
-    # Synthetic tool_result message when a tool is skipped due to user interrupt.
-    INTERRUPT_MESSAGE = "Stopped by user"
+    # Synthetic tool_result when a tool is skipped because the human pressed Escape.
+    INTERRUPT_MESSAGE = "Your human wants your attention"
 
     # @return [Providers::Anthropic] the underlying API provider
     attr_reader :provider
@@ -65,7 +65,7 @@ module LLM
     # tool interaction so they're persisted and visible in the event stream.
     #
     # When the user interrupts via Escape, remaining tools receive synthetic
-    # "Stopped by user" results and the loop exits without another LLM call.
+    # "Your human wants your attention" results and the loop exits without another LLM call.
     #
     # @param messages [Array<Hash>] conversation messages in Anthropic format
     # @param registry [Tools::Registry] registered tools to make available
@@ -90,6 +90,7 @@ module LLM
         response = if first_response && rounds == 1
           first_response
         else
+          broadcast_session_state(session_id, "llm_generating")
           provider.create_message(
             model: model,
             messages: messages,
@@ -109,11 +110,14 @@ module LLM
             {role: "user", content: tool_results}
           ]
 
-          if interrupted?(session_id)
-            clear_interrupt!(session_id)
-            return nil
-          end
+          return nil if handle_interrupt!(session_id)
         else
+          # Discard the text response if the user pressed Escape while
+          # the API was generating it. Without this check the interrupt
+          # flag set during the blocking API call would be silently
+          # cleared by the ensure block in AgentRequestJob.
+          return nil if handle_interrupt!(session_id)
+
           return extract_text(response)
         end
       end
@@ -151,9 +155,12 @@ module LLM
     def execute_tools(response, registry, session_id)
       tool_uses = extract_tool_uses(response)
       results = []
+      interrupted = false
 
       tool_uses.each_with_index do |tool_use, index|
-        if interrupted?(session_id)
+        # Check-only here; clearing happens in handle_interrupt! after the loop
+        interrupted ||= interrupt_requested?(session_id)
+        if interrupted
           remaining = tool_uses[index..]
           results.concat(interrupt_remaining_tools(remaining, session_id)) if remaining&.any?
           break
@@ -164,7 +171,7 @@ module LLM
       results
     end
 
-    # Creates synthetic "Stopped by user" results for all tools in the list.
+    # Creates synthetic "Your human wants your attention" results for all tools in the list.
     #
     # @param tool_uses [Array<Hash>] remaining tool_use content blocks
     # @param session_id [Integer, String] session ID for events
@@ -188,6 +195,8 @@ module LLM
 
       log(:debug, "tool_call: #{name}(#{input.to_json})")
 
+      broadcast_session_state(session_id, "tool_executing", tool: name)
+
       Events::Bus.emit(Events::ToolCall.new(
         content: "Calling #{name}", tool_name: name,
         tool_input: input, tool_use_id: id, timeout: timeout,
@@ -197,6 +206,7 @@ module LLM
       result = registry.execute(name, input)
       result = ToolDecorator.call(name, result)
       result_content = format_tool_result(result)
+      result_content = truncate_tool_result(result_content, registry, name)
       log(:debug, "tool_result: #{name} → #{result_content.to_s.truncate(200)}")
 
       Events::Bus.emit(Events::ToolResponse.new(
@@ -225,7 +235,7 @@ module LLM
       {type: "tool_result", tool_use_id: id, content: error_content}
     end
 
-    # Creates a synthetic "Stopped by user" result for a tool that was not
+    # Creates a synthetic "Your human wants your attention" result for a tool that was not
     # executed due to user interrupt. Emits both ToolCall and ToolResponse
     # events so the TUI shows the interrupted tool in the event stream.
     #
@@ -238,7 +248,7 @@ module LLM
       input = tool_use["input"] || {}
 
       Events::Bus.emit(Events::ToolCall.new(
-        content: "Skipped #{name} (interrupted)", tool_name: name,
+        content: "Skipped #{name} — your human wants your attention", tool_name: name,
         tool_input: input, tool_use_id: id, session_id: session_id
       ))
 
@@ -250,22 +260,35 @@ module LLM
       {type: "tool_result", tool_use_id: id, content: INTERRUPT_MESSAGE}
     end
 
-    # Checks the database for a pending interrupt flag on the session.
+    # Checks whether the session has a pending interrupt flag.
     #
     # @param session_id [Integer, String] session to check
-    # @return [Boolean] whether the session has a pending interrupt request
-    def interrupted?(session_id)
+    # @return [Boolean] true when interrupt is pending
+    def interrupt_requested?(session_id)
       Session.where(id: session_id, interrupt_requested: true).exists?
     end
 
-    # Clears the interrupt flag so the agent loop can continue with pending
-    # messages. Also cleared by {AgentRequestJob#clear_interrupt} as a safety
-    # net for unexpected exits.
+    # Atomically checks for a pending interrupt and clears it in one query.
+    # Used at loop boundaries (after tools, before LLM text return) to
+    # short-circuit the agent loop when the user presses Escape.
     #
-    # @param session_id [Integer, String] session to clear
+    # @param session_id [Integer, String] session to check
+    # @return [Boolean] true when interrupt was detected and cleared
+    def handle_interrupt!(session_id)
+      Session.where(id: session_id, interrupt_requested: true)
+        .update_all(interrupt_requested: false) > 0
+    end
+
+    # Broadcasts a session state transition to all subscribed clients.
+    # Delegates to {Session#broadcast_session_state} which handles both
+    # the session's own stream and the parent's stream for HUD updates.
+    #
+    # @param session_id [Integer, String] session to broadcast for
+    # @param state [String] one of "idle", "llm_generating", "tool_executing", "interrupting"
+    # @param tool [String, nil] tool name when state is "tool_executing"
     # @return [void]
-    def clear_interrupt!(session_id)
-      Session.where(id: session_id).update_all(interrupt_requested: false)
+    def broadcast_session_state(session_id, state, tool: nil)
+      Session.find_by(id: session_id)&.broadcast_session_state(state, tool: tool)
     end
 
     def log(level, message)
@@ -277,5 +300,16 @@ module LLM
     def format_tool_result(result)
       result.is_a?(Hash) ? result.to_json : result.to_s
     end
+
+    # Applies head+tail truncation when a tool result exceeds the tool's
+    # configured character threshold. Skips tools that opt out (e.g. read).
+    def truncate_tool_result(content, registry, tool_name)
+      threshold = registry.truncation_threshold(tool_name)
+      return content unless threshold
+
+      lines = Tools::ResponseTruncator::HEAD_LINES
+      reason = "#{tool_name} output displays first/last #{lines} lines"
+      Tools::ResponseTruncator.truncate(content, threshold: threshold, reason: reason)
+    end
   end
 end