anima-core 1.2.0 → 1.3.0

data/lib/mcp/config.rb

@@ -6,7 +6,7 @@ require "toml-rb"
 module Mcp
   # Reads and writes MCP server configuration from a TOML file at
   # {DEFAULT_PATH}. Supports HTTP and stdio transports. Secrets stored
-  # in Rails encrypted credentials are interpolated via
+  # in the encrypted secrets table are interpolated via
   # +${credential:key_name}+ syntax in any string value.
   #
   # @example Config file format (~/.anima/mcp.toml)
@@ -187,7 +187,7 @@ module Mcp
     end
 
     # Replaces +${credential:key_name}+ placeholders with values from
-    # Rails encrypted credentials via {Mcp::Secrets}.
+    # the encrypted secrets table via {Mcp::Secrets}.
     #
     # @param value [String] string potentially containing placeholders
     # @return [String] interpolated string

data/lib/mcp/secrets.rb

@@ -1,12 +1,11 @@
 # frozen_string_literal: true
 
 module Mcp
-  # CRUD operations for MCP server secrets stored in Rails encrypted credentials.
-  # Secrets live under the +mcp+ namespace in the credentials file:
+  # CRUD operations for MCP server secrets stored in the encrypted secrets table.
+  # Secrets live under the +mcp+ namespace:
   #
-  #   mcp:
-  #     linear_api_key: "sk-xxx"
-  #     mythonix_api_key: "Bearer tok-yyy"
+  #   Mcp::Secrets.set("linear_api_key", "sk-xxx")
+  #   Mcp::Secrets.get("linear_api_key") #=> "sk-xxx"
   #
   # Referenced in mcp.toml via +${credential:key_name}+ syntax, resolved at
   # runtime by {Mcp::Config#interpolate_credentials}.
@@ -23,7 +22,7 @@ module Mcp
     VALID_KEY_PATTERN = /\A\w+\z/
 
     class << self
-      # Stores a secret in encrypted credentials.
+      # Stores a secret in encrypted storage.
       #
       # @param key [String] secret identifier (e.g. "linear_api_key")
       # @param value [String] secret value
@@ -35,7 +34,7 @@ module Mcp
         CredentialStore.write(NAMESPACE, key => value)
       end
 
-      # Retrieves a secret from encrypted credentials.
+      # Retrieves a secret from encrypted storage.
       #
       # @param key [String] secret identifier
       # @return [String, nil] secret value or nil if not found
@@ -50,7 +49,7 @@ module Mcp
         CredentialStore.list(NAMESPACE)
       end
 
-      # Removes a secret from encrypted credentials.
+      # Removes a secret from encrypted storage.
       #
       # @param key [String] secret identifier to remove
       # @return [void]

data/lib/mneme/compressed_viewport.rb

@@ -57,7 +57,7 @@ module Mneme
     #
     # @return [Array<Message>]
     def fetch_messages
-      scope = @session.messages.context_messages.deliverable
+      scope = @session.messages.context_messages
 
       if @from_message_id
         scope = scope.where("id >= ?", @from_message_id)

data/lib/shell_session.rb

@@ -47,13 +47,17 @@ class ShellSession
   # @param command [String] bash command to execute
   # @param timeout [Integer, nil] per-call timeout in seconds; overrides
   #   Settings.command_timeout when provided
+  # @param interrupt_check [Proc, nil] callable returning truthy when the
+  #   user has requested an interrupt. Polled every
+  #   {Anima::Settings.interrupt_check_interval} seconds during command execution.
   # @return [Hash] with :stdout, :stderr, :exit_code keys on success
+  # @return [Hash] with :interrupted, :stdout, :stderr keys on user interrupt
   # @return [Hash] with :error key on failure
-  def run(command, timeout: nil)
+  def run(command, timeout: nil, interrupt_check: nil)
     @mutex.synchronize do
       return {error: "Shell session is not running"} if @finalized
       restart unless @alive
-      execute_in_pty(command, timeout: timeout)
+      execute_in_pty(command, timeout: timeout, interrupt_check: interrupt_check)
     end
   rescue => error # rubocop:disable Lint/RescueException -- LLM must always get a result hash, never a stack trace
     {error: "#{error.class}: #{error.message}"}
@@ -229,7 +233,7 @@ class ShellSession
     end
   end
 
-  def execute_in_pty(command, timeout: nil)
+  def execute_in_pty(command, timeout: nil, interrupt_check: nil)
     clear_stderr
     marker = "__ANIMA_#{SecureRandom.hex(8)}__"
     timeout ||= Anima::Settings.command_timeout
@@ -237,10 +241,21 @@ class ShellSession
 
     @pty_stdin.puts "#{command}; __anima_ec=$?; echo; echo '#{marker}' $__anima_ec"
 
-    stdout, exit_code = read_until_marker(marker, deadline: deadline)
+    stdout, exit_code = read_until_marker(marker, deadline: deadline, interrupt_check: interrupt_check)
+
+    if exit_code == :interrupted
+      recover_shell
+      update_pwd
+      stderr = drain_stderr
+      return {
+        interrupted: true,
+        stdout: truncate(stdout),
+        stderr: truncate(stderr)
+      }
+    end
 
     if exit_code.nil?
-      recover_from_timeout
+      recover_shell
       stderr = drain_stderr
       parts = ["Command timed out after #{timeout} seconds."]
       parts << "Partial stdout:\n#{truncate(stdout)}" unless stdout.empty?
@@ -267,14 +282,23 @@ class ShellSession
   #
   # @param marker [String] unique marker to detect command completion
   # @param deadline [Float] monotonic clock deadline
+  # @param interrupt_check [Proc, nil] callable returning truthy on user interrupt
   # @return [Array(String, Integer)] stdout and exit code on success
+  # @return [Array(String, Symbol)] partial stdout and +:interrupted+ on user interrupt
   # @return [Array(String, nil)] partial stdout and nil exit code on timeout
-  def read_until_marker(marker, deadline:)
+  def read_until_marker(marker, deadline:, interrupt_check: nil)
     lines = []
     exit_code = nil
+    check_interval = interrupt_check ? [Anima::Settings.interrupt_check_interval, 0.5].max : nil
 
     loop do
-      line = gets_with_deadline(deadline)
+      line = gets_with_deadline(deadline, interrupt_check: interrupt_check, check_interval: check_interval)
+
+      if line == :interrupted
+        exit_code = :interrupted
+        break
+      end
+
       break if line.nil?
 
       line = line.chomp.delete("\r")
@@ -315,12 +339,21 @@ class ShellSession
   # Timeout.timeout (which uses Thread.raise that can corrupt mutex state
   # and leave resources inconsistent).
   #
+  # When +interrupt_check+ is provided, IO.select uses a shorter timeout
+  # (capped at {Anima::Settings.interrupt_check_interval}) and polls the
+  # callback between iterations. Returns +:interrupted+ when the callback
+  # fires, allowing the caller to send Ctrl+C and return partial output.
+  #
   # @param deadline [Float] monotonic clock deadline
+  # @param interrupt_check [Proc, nil] callable returning truthy on user interrupt
+  # @param check_interval [Float, nil] resolved interrupt check interval (seconds);
+  #   pre-computed by the caller to avoid re-reading Settings on every line
   # @return [String] line including trailing newline
+  # @return [:interrupted] when user interrupt detected
   # @return [nil] if deadline expired
   # @raise [Errno::EIO] when the PTY child process exits (Linux)
   # @raise [IOError] when the PTY file descriptor is closed
-  def gets_with_deadline(deadline)
+  def gets_with_deadline(deadline, interrupt_check: nil, check_interval: nil)
     loop do
       if (idx = @read_buffer.index("\n"))
         return @read_buffer.slice!(0..idx)
@@ -329,24 +362,29 @@ class ShellSession
       remaining = deadline - monotonic_now
       return nil if remaining <= 0
 
-      ready = IO.select([@pty_stdout], nil, nil, remaining)
-      return nil unless ready
+      select_timeout = check_interval ? [remaining, check_interval].min : remaining
 
-      begin
-        @read_buffer << @pty_stdout.read_nonblock(4096)
-      rescue IO::WaitReadable
-        # Spurious wakeup from IO.select — retry
+      ready = IO.select([@pty_stdout], nil, nil, select_timeout)
+
+      if ready
+        begin
+          @read_buffer << @pty_stdout.read_nonblock(4096)
+        rescue IO::WaitReadable
+          # Spurious wakeup from IO.select — retry
+        end
       end
+
+      return :interrupted if interrupt_check&.call
     end
   end
 
-  # Sends Ctrl+C to interrupt the running command and drains leftover output.
+  # Sends Ctrl+C and drains leftover output after a timeout or user interrupt.
   # If recovery fails, marks the session as dead (will be respawned on next run).
   #
   # @return [void]
   # @raise [Errno::EIO] when the PTY child process has exited
   # @raise [IOError] when the PTY file descriptor is closed
-  def recover_from_timeout
+  def recover_shell
     @pty_stdin.write("\x03")
     sleep 0.1
     marker = "__ANIMA_RECOVER_#{SecureRandom.hex(8)}__"

data/lib/tools/base.rb

@@ -41,8 +41,31 @@ module Tools
       def schema
         {name: tool_name, description: description, input_schema: input_schema}
       end
+
+      # Per-tool character threshold for response truncation.
+      # Override in subclasses to use a custom limit, or return +nil+
+      # to skip truncation entirely (e.g. read_file tool has its own pagination).
+      #
+      # @return [Integer, nil] character threshold, or nil to skip truncation
+      def truncation_threshold
+        Anima::Settings.max_tool_response_chars
+      end
     end
 
+    # Subclasses whose schema depends on runtime context (e.g. session state,
+    # shell working directory) can implement +#dynamic_schema+. The registry
+    # calls it instead of the class-level {.schema} when present.
+    #
+    # @example
+    #   def dynamic_schema
+    #     schema = self.class.schema.deep_dup
+    #     schema[:description] = "Dynamic: #{@some_state}"
+    #     schema
+    #   end
+    #
+    # @see Think#dynamic_schema Budget-based maxLength
+    # @see Bash#dynamic_schema CWD in description
+
     # Accepts and discards context keywords so that the Registry can pass
     # shared dependencies (e.g. shell_session) to any tool uniformly.
     # Subclasses that need specific context should override with named kwargs.

data/lib/tools/bash.rb

@@ -38,8 +38,21 @@ module Tools
     end
 
     # @param shell_session [ShellSession] persistent shell backing this tool
-    def initialize(shell_session:, **)
+    # @param session [Session] conversation session for interrupt checking
+    def initialize(shell_session:, session:, **)
       @shell_session = shell_session
+      @session = session
+    end
+
+    # Returns tool schema with the shell's current working directory
+    # embedded in the description so the agent sees it during tool
+    # selection — eliminating redundant +cd+ prefixes.
+    #
+    # @return [Hash] Anthropic tool schema with dynamic description
+    def dynamic_schema
+      schema = self.class.schema.deep_dup
+      schema[:description] = "Execute shell commands in #{@shell_session.pwd}. Working directory and environment persist between calls."
+      schema
     end
 
     # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API.
@@ -70,13 +83,18 @@ module Tools
       command = command.to_s
       return {error: "Command cannot be blank"} if command.strip.empty?
 
-      result = @shell_session.run(command, timeout: timeout)
+      result = @shell_session.run(command, timeout: timeout, interrupt_check: interrupt_checker)
+
+      return format_interrupted(result) if result[:interrupted]
       return result if result.key?(:error)
 
       format_result(result[:stdout], result[:stderr], result[:exit_code])
     end
 
     # Executes an array of commands, returning a combined result string.
+    # Checks for user interrupt between commands and during each command
+    # via the {ShellSession} interrupt_check callback.
+    #
     # @param commands [Array<String>] commands to execute
     # @param mode [String] "sequential" (stop on first failure) or "parallel" (run all)
     # @param timeout [Integer, nil] per-command timeout override
@@ -85,13 +103,20 @@ module Tools
     def execute_batch(commands, mode:, timeout: nil)
       return {error: "Commands array cannot be empty"} unless commands.is_a?(Array) && commands.any?
 
+      checker = interrupt_checker
       total = commands.size
       results = []
       failed = false
+      interrupted = false
 
       commands.each_with_index do |command, index|
         position = "[#{index + 1}/#{total}]"
 
+        if interrupted
+          results << "#{position} $ #{command}\n(skipped — interrupted by user)"
+          next
+        end
+
         if failed && mode == "sequential"
           results << "#{position} $ #{command}\n(skipped)"
           next
@@ -103,9 +128,12 @@ module Tools
           next
         end
 
-        result = @shell_session.run(command, timeout: timeout)
+        result = @shell_session.run(command, timeout: timeout, interrupt_check: checker)
 
-        if result.key?(:error)
+        if result[:interrupted]
+          results << "#{position} $ #{command}\n#{format_interrupted(result)}"
+          interrupted = true
+        elsif result.key?(:error)
           results << "#{position} $ #{command}\n#{result[:error]}"
           failed = true
         else
@@ -126,5 +154,29 @@ module Tools
       parts << "exit_code: #{exit_code}"
       parts.join("\n\n")
     end
+
+    # Formats the result of an interrupted command for the LLM.
+    # Includes partial output captured before the interrupt.
+    #
+    # @param result [Hash] ShellSession result with :stdout, :stderr keys
+    # @return [String] formatted message for the LLM
+    def format_interrupted(result)
+      stdout = result[:stdout].to_s
+      stderr = result[:stderr].to_s
+      parts = [LLM::Client::INTERRUPT_MESSAGE]
+      parts << "Partial stdout:\n#{stdout}" unless stdout.empty?
+      parts << "stderr:\n#{stderr}" unless stderr.empty?
+      parts.join("\n\n")
+    end
+
+    # Builds a lambda that checks the database for a pending interrupt flag.
+    # Called every {Anima::Settings.interrupt_check_interval} seconds during
+    # command execution inside {ShellSession}.
+    #
+    # @return [Proc] lambda returning truthy when interrupt is pending
+    def interrupt_checker
+      session_id = @session.id
+      -> { Session.where(id: session_id, interrupt_requested: true).exists? }
+    end
   end
 end

data/lib/tools/edit.rb

@@ -16,7 +16,7 @@ module Tools
   #                "new_text" => "def greet\n  'hello'\nend")
   #   # => "--- app.rb\n+++ app.rb\n@@ -1,3 +1,3 @@\n ..."
   class Edit < Base
-    def self.tool_name = "edit"
+    def self.tool_name = "edit_file"
 
     def self.description = "Replace text in a file."
 
@@ -132,7 +132,7 @@ module Tools
 
       {error: "Could not find old_text in #{path}. " \
               "Verify the text exists and matches exactly (including whitespace). " \
-              "Use the read tool to check current file contents."}
+              "Use the read_file tool to check current file contents."}
     end
 
     def ambiguity_error(positions, content, path, fuzzy: false)

data/lib/tools/mark_goal_completed.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Tools
+  # Signals sub-agent task completion by marking its assigned Goal as
+  # completed and routing the result back to the parent session.
+  #
+  # Only available to sub-agent sessions (those with a +parent_session+).
+  # This is the explicit "finish line" that prevents runaway sub-agents
+  # from continuing past their assigned task.
+  #
+  # The result text is delivered to the parent session as a user message
+  # attributed to the sub-agent, identical to how regular sub-agent
+  # messages are routed by {Events::Subscribers::SubagentMessageRouter}.
+  #
+  # @example Sub-agent completing its task
+  #   mark_goal_completed(result: "Found 3 N+1 queries in the orders controller.")
+  class MarkGoalCompleted < Base
+    def self.tool_name = "mark_goal_completed"
+
+    def self.description = "Deliver result to parent. Stop working after this call."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          result: {type: "string"}
+        },
+        required: %w[result]
+      }
+    end
+
+    # @param session [Session] the sub-agent session
+    def initialize(session:, **)
+      @session = session
+    end
+
+    # Completes the sub-agent's assigned goal and routes the result
+    # to the parent session.
+    #
+    # @param input [Hash<String, Object>] with "result"
+    # @return [String] confirmation message
+    # @return [Hash{Symbol => String}] with :error key on failure
+    def execute(input)
+      result = input["result"].to_s.strip
+      return {error: "Result cannot be blank"} if result.empty?
+
+      goal = @session.goals.active.root.first
+      return {error: "No active goal found"} unless goal
+
+      complete_goal(goal)
+      route_result_to_parent(result)
+
+      "Done. Result delivered to parent."
+    end
+
+    private
+
+    def complete_goal(goal)
+      Goal.transaction do
+        goal.update!(status: "completed", completed_at: Time.current)
+        goal.cascade_completion!
+        goal.release_orphaned_pins!
+      end
+    end
+
+    # Delivers the sub-agent's result to the parent session as an
+    # attributed user message. Truncates oversized results to protect
+    # the parent's context window. No-op when the parent session is absent.
+    #
+    # @param result [String] the sub-agent's findings to forward
+    # @return [void]
+    def route_result_to_parent(result)
+      parent = @session.parent_session
+      return unless parent
+
+      name = @session.name || "agent-#{@session.id}"
+      truncated = Tools::ResponseTruncator.truncate(
+        result,
+        threshold: Anima::Settings.max_subagent_response_chars,
+        reason: "sub-agent output displays first/last #{Tools::ResponseTruncator::HEAD_LINES} lines"
+      )
+      attributed = format(Tools::ResponseTruncator::ATTRIBUTION_FORMAT, name, truncated)
+      parent.enqueue_user_message(attributed)
+    end
+  end
+end

data/lib/tools/read.rb

@@ -16,7 +16,8 @@ module Tools
   #   tool.execute("path" => "large.log", "offset" => 2001, "limit" => 500)
   #   # => "line 2001 content\n..."
   class Read < Base
-    def self.tool_name = "read"
+    def self.tool_name = "read_file"
+    def self.truncation_threshold = nil
 
     def self.description = "Read file. Relative paths resolve against working directory."
 

data/lib/tools/recall.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Tools
+  # Active memory search — keyword lookup across conversation history.
+  # Returns ranked snippets with message IDs for drill-down via {Remember}.
+  #
+  # Two-step memory workflow:
+  #   1. `recall(query: "auth flow")` → discovers relevant messages
+  #   2. `remember(message_id: 42)` → fractal zoom into full context
+  #
+  # Wraps {Mneme::Search} — same FTS5 engine used by passive recall,
+  # but triggered on demand by the agent instead of automatically by goals.
+  #
+  # @example Search all sessions
+  #   recall(query: "authentication flow")
+  #
+  # @example Search current session only
+  #   recall(query: "OAuth config", session_only: true)
+  class Recall < Base
+    def self.tool_name = "recall"
+
+    def self.description = "Find messages across past conversations by keywords."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          query: {type: "string"},
+          session_only: {type: "boolean", description: "Default: all sessions"}
+        },
+        required: ["query"]
+      }
+    end
+
+    # @param session [Session] the current session (used for session_only scoping)
+    def initialize(session:, **)
+      @session = session
+    end
+
+    # @param input [Hash] with "query" and optional "session_only"
+    # @return [String] formatted search results with message IDs
+    # @return [Hash] with :error key when query is blank
+    def execute(input)
+      query = input["query"].to_s.strip
+      return {error: "Query cannot be blank"} if query.empty?
+
+      session_id = (input["session_only"] == true) ? @session.id : nil
+      results = Mneme::Search.query(query, session_id: session_id)
+
+      return "No results found for \"#{query}\"." if results.empty?
+
+      format_results(query, results)
+    end
+
+    private
+
+    # Formats results as token-efficient, LLM-readable output.
+    # Each result includes message_id for drill-down via remember tool.
+    #
+    # @param query [String] the original search query
+    # @param results [Array<Mneme::Search::Result>] ranked search results
+    # @return [String] formatted output
+    def format_results(query, results)
+      session_names = load_session_names(results)
+
+      result_word = (results.size == 1) ? "result" : "results"
+      lines = ["Found #{results.size} #{result_word} for \"#{query}\":", ""]
+      results.each { |result| lines.concat(format_single_result(result, session_names)) }
+      lines.join("\n")
+    end
+
+    # Formats a single search result as display lines.
+    #
+    # @param result [Mneme::Search::Result]
+    # @param session_names [Hash{Integer => String}]
+    # @return [Array<String>]
+    def format_single_result(result, session_names)
+      sid = result.session_id
+      session_name = session_names[sid] || "Session ##{sid}"
+      snippet = result.snippet.to_s.gsub(/\s+/, " ").strip
+
+      [
+        "[message #{result.message_id}, session \"#{session_name}\", #{result.message_type}]",
+        "  ...#{snippet}...",
+        ""
+      ]
+    end
+
+    # Batch-loads session names to avoid N+1 queries.
+    #
+    # @param results [Array<Mneme::Search::Result>]
+    # @return [Hash{Integer => String}] session_id => name
+    def load_session_names(results)
+      session_ids = results.map(&:session_id).uniq
+      Session.where(id: session_ids).pluck(:id, :name).to_h
+    end
+  end
+end

data/lib/tools/registry.rb

@@ -33,10 +33,14 @@ module Tools
     # @return [Array<Hash>] schema array for the Anthropic tools API parameter.
     #   Each schema includes an optional `timeout` parameter (seconds) injected
     #   by the registry. The agent can override the default per call for
-    #   long-running operations.
+    #   long-running operations. Tools with session-dependent schemas (e.g.
+    #   {Think} with budget-based maxLength, {Bash} with CWD in description)
+    #   are instantiated with context to generate their schema:
+    #   - {Think}: budget-based maxLength
+    #   - {Bash}: CWD embedded in description
     def schemas
       default = Anima::Settings.tool_timeout
-      @tools.values.map { |tool| inject_timeout(tool.schema, default) }
+      @tools.values.map { |tool| inject_timeout(resolve_schema(tool), default) }
     end
 
     # Execute a tool by name. Classes are instantiated with the registry's
@@ -53,6 +57,19 @@ module Tools
       instance.execute(input)
     end
 
+    # Returns the truncation threshold for a tool, or +nil+ if the tool
+    # opts out of truncation (e.g. read_file tool has its own pagination).
+    # MCP tools and other duck-typed instances use the default threshold.
+    #
+    # @param name [String] registered tool name
+    # @return [Integer, nil] character threshold, or nil to skip truncation
+    def truncation_threshold(name)
+      tool = @tools[name]
+      return tool.truncation_threshold if tool&.respond_to?(:truncation_threshold)
+
+      Anima::Settings.max_tool_response_chars
+    end
+
     # @param name [String] tool name to check
     # @return [Boolean] whether a tool with the given name is registered
     def registered?(name)
@@ -66,16 +83,28 @@ module Tools
 
     private
 
+    # Returns a tool's schema, preferring the instance-level dynamic
+    # variant when available. Only instantiates the tool when needed.
+    def resolve_schema(tool)
+      return tool.schema unless dynamic_schema?(tool)
+
+      tool.new(**@context).dynamic_schema
+    end
+
+    def dynamic_schema?(tool)
+      tool.is_a?(Class) && tool.method_defined?(:dynamic_schema)
+    end
+
     # Injects an optional `timeout` parameter into the tool's input schema.
     def inject_timeout(schema, default)
-      s = schema.deep_dup
-      s[:input_schema] ||= {type: "object", properties: {}}
-      s[:input_schema][:properties] ||= {}
-      s[:input_schema][:properties]["timeout"] = {
+      result = schema.deep_dup
+      input = result[:input_schema] ||= {type: "object", properties: {}}
+      props = input[:properties] ||= {}
+      props["timeout"] = {
         type: "integer",
         description: "Seconds (default: #{default})."
       }
-      s
+      result
     end
   end
 end

data/lib/tools/remember.rb

@@ -112,7 +112,7 @@ module Tools
     # @return [Array<Message>] chronologically ordered
     def fetch_center_messages(target, target_session)
       half = CONTEXT_WINDOW / 2
-      scope = target_session.messages.context_messages.deliverable
+      scope = target_session.messages.context_messages
       target_id = target.id
 
       before = scope.where("id <= ?", target_id).reorder(id: :desc).limit(half + 1).to_a.reverse