anima-core 1.2.0 → 1.4.0

data/lib/tools/bash.rb

@@ -38,8 +38,10 @@ 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
 
     # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API.
@@ -65,18 +67,24 @@ module Tools
 
     private
 
-    # Executes a single command — the original code path, preserved for backward compatibility.
+    # Executes a single command — the original code path.
     def execute_single(command, timeout: nil)
       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])
+      output = format_result(result[:stdout], result[:stderr], result[:exit_code])
+      append_env_summary(output, result[:env_summary])
     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 +93,22 @@ 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
+
+      last_env_summary = nil
 
       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,20 +120,33 @@ 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
           exit_code = result[:exit_code]
           output = format_result(result[:stdout], result[:stderr], exit_code)
           results << "#{position} $ #{command}\n#{output}"
+          last_env_summary = result[:env_summary]
           failed = true if exit_code != 0
         end
       end
 
-      results.join("\n\n")
+      append_env_summary(results.join("\n\n"), last_env_summary)
+    end
+
+    # Appends environment summary to tool output when present.
+    #
+    # @param output [String] formatted tool response
+    # @param env_summary [String, nil] natural-language environment change summary
+    # @return [String] output with env summary appended
+    def append_env_summary(output, env_summary)
+      env_summary ? "#{output}\n\n#{env_summary}" : output
     end
 
     def format_result(stdout, stderr, exit_code)
@@ -126,5 +156,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,85 @@
+# 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 with source
+    # metadata. 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"
+      )
+      parent.enqueue_user_message(truncated, source_type: "subagent", source_name: name)
+    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,19 @@ 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
+    # Returns tool schemas for the Anthropic API. The last schema is
+    # annotated with +cache_control+ so the API caches the entire tools
+    # prefix (tools are evaluated first in cache prefix order).
     def schemas
       default = Anima::Settings.tool_timeout
-      @tools.values.map { |tool| inject_timeout(tool.schema, default) }
+      result = @tools.values.map { |tool| inject_timeout(resolve_schema(tool), default) }
+      result.last[:cache_control] = {type: "ephemeral"}
+      result
     end
 
     # Execute a tool by name. Classes are instantiated with the registry's
@@ -53,6 +62,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 +88,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

data/lib/tools/response_truncator.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module Tools
+  # Truncates oversized tool results to protect the agent's context window.
+  #
+  # When a tool returns more characters than the configured threshold,
+  # saves the full output to a temp file and returns a truncated version:
+  # first 10 lines + notice + last 10 lines. The agent can use the
+  # +read_file+ tool with offset/limit to inspect the full output.
+  #
+  # Two thresholds exist:
+  # - **Tool threshold** (~3000 chars) — for raw tool output (bash, web, etc.)
+  # - **Sub-agent threshold** (~24000 chars) — for curated sub-agent results
+  #
+  # @example Truncating a tool result
+  #   ResponseTruncator.truncate(huge_string, threshold: 3000)
+  #   # => "line 1\nline 2\n...\n---\n⚠️ Response truncated..."
+  module ResponseTruncator
+    HEAD_LINES = 10
+    TAIL_LINES = 10
+
+    # Attribution prefix for messages routed from sub-agent to parent.
+    # Shared by {Events::Subscribers::SubagentMessageRouter} and
+    # {Tools::MarkGoalCompleted} to keep formatting consistent.
+    ATTRIBUTION_FORMAT = "[sub-agent %s]: %s"
+
+    NOTICE = <<~NOTICE.strip
+      ---
+      ⚠️ Response truncated (%<total>d lines total%<reason>s). Full output saved to: %<path>s
+      Use `read_file` tool with offset/limit to inspect specific sections.
+      ---
+    NOTICE
+
+    # Truncates content that exceeds the character threshold.
+    #
+    # @param content [Object] the tool result to (maybe) truncate; non-strings pass through unchanged
+    # @param threshold [Integer] character limit before truncation kicks in
+    # @param reason [String, nil] why truncation occurred (e.g. "bash output displays first/last 10 lines")
+    # @return [Object] original value if non-String/under threshold/few lines, truncated String otherwise
+    def self.truncate(content, threshold:, reason: nil)
+      return content unless content.is_a?(String)
+      return content if content.length <= threshold
+
+      lines = content.lines
+      total = lines.size
+      return content if total <= HEAD_LINES + TAIL_LINES
+
+      path = save_full_output(content)
+      head = lines.first(HEAD_LINES).join
+      tail = lines.last(TAIL_LINES).join
+      reason_text = reason ? " — #{reason}" : ""
+      notice = format(NOTICE, total: total, path: path, reason: reason_text)
+
+      "#{head}\n#{notice}\n\n#{tail}"
+    end
+
+    # Saves full content to a temp file that persists until system cleanup.
+    #
+    # @param content [String] the full tool result
+    # @return [String] absolute path to the saved file
+    def self.save_full_output(content)
+      file = Tempfile.create(["tool_result_", ".txt"])
+      file.write(content)
+      file.close
+      file.path
+    end
+  end
+end

data/lib/tools/spawn_specialist.rb

@@ -21,9 +21,9 @@ module Tools
 
     # Builds description dynamically to include available specialists.
     def self.description
-      base = "Spawn a specialist to work on a task. " \
-        "Its messages are forwarded to you. " \
-        "Address it via @name to send follow-up instructions."
+      base = "Need a specific skill set for the job? Bring in a specialist. " \
+        "Its messages appear as tool responses in your conversation. " \
+        "Prefix its nickname with @ to send instructions."
 
       registry = Agents::Registry.instance
       return base unless registry.any?
@@ -58,9 +58,11 @@ module Tools
     private_class_method :name_property
 
     # @param session [Session] the parent session spawning the specialist
+    # @param shell_session [ShellSession] the parent's persistent shell (for CWD inheritance)
     # @param agent_registry [Agents::Registry, nil] injectable for testing
-    def initialize(session:, agent_registry: nil, **)
+    def initialize(session:, shell_session:, agent_registry: nil, **)
       @session = session
+      @shell_session = shell_session
       @agent_registry = agent_registry || Agents::Registry.instance
     end
 
@@ -83,9 +85,9 @@ module Tools
 
       child = spawn_child(definition, task)
       nickname = child.name
-      "Specialist @#{nickname} spawned (session #{child.id}). " \
+      "Specialist #{nickname} spawned (session #{child.id}). " \
         "Its messages will appear in your conversation. " \
-        "Reply with @#{nickname} to send it instructions."
+        "To address it, prefix its name with @ in your message."
     end
 
     private
@@ -94,9 +96,10 @@ module Tools
       child = Session.create!(
         parent_session_id: @session.id,
         prompt: build_prompt(definition),
-        granted_tools: definition.tools
+        granted_tools: definition.tools,
+        initial_cwd: @shell_session.pwd
       )
-      child.create_user_message(task)
+      create_goal_with_pinned_task(child, task)
       assign_nickname_via_brain(child)
       child.broadcast_children_update_to_parent
       AgentRequestJob.perform_later(child.id)

data/lib/tools/spawn_subagent.rb

@@ -2,8 +2,9 @@
 
 module Tools
   # Spawns a generic child session that works on a task autonomously.
-  # The sub-agent inherits the parent's viewport context at fork time,
-  # runs via {AgentRequestJob}, and communicates with the parent through
+  # The sub-agent starts clean — no parent conversation history — with
+  # only a system prompt, a Goal, and the task as its first user message.
+  # Runs via {AgentRequestJob} and communicates with the parent through
   # natural text messages routed by {Events::Subscribers::SubagentMessageRouter}.
   #
   # Nickname assignment is handled by the {AnalyticalBrain::Runner} which
@@ -14,14 +15,15 @@ module Tools
   class SpawnSubagent < Base
     include SubagentPrompts
 
-    GENERIC_PROMPT = "You are a focused sub-agent. #{COMMUNICATION_INSTRUCTION}\n"
+    GENERIC_PROMPT = "#{COMMUNICATION_INSTRUCTION}\n"
 
     def self.tool_name = "spawn_subagent"
 
     def self.description
-      "Spawn a sub-agent to work on a task. " \
-        "It inherits your conversation context and its messages are forwarded to you. " \
-        "Address it via @nickname to send follow-up instructions."
+      "Task feels like a sidequest or a context-switch? Hand it off. " \
+        "Starts clean with just the task — include all relevant context in the task description. " \
+        "Its messages appear as tool responses in your conversation. " \
+        "Prefix its nickname with @ to send instructions."
     end
 
     def self.input_schema
@@ -42,12 +44,15 @@ module Tools
     end
 
     # @param session [Session] the parent session spawning the sub-agent
-    def initialize(session:, **)
+    # @param shell_session [ShellSession] the parent's persistent shell (for CWD inheritance)
+    def initialize(session:, shell_session:, **)
       @session = session
+      @shell_session = shell_session
     end
 
-    # Creates a child session, runs the analytical brain to assign a nickname,
-    # persists the task as a user message, and queues background processing.
+    # Creates a child session with a clean context (no parent history),
+    # runs the analytical brain to assign a nickname, persists the task
+    # as a pinned user message, and queues background processing.
     # Returns immediately after brain completes (blocking for ~200ms).
     #
     # @param input [Hash<String, Object>] with "task" and optional "tools"
@@ -65,9 +70,9 @@ module Tools
 
       child = spawn_child(task, tools)
       nickname = child.name
-      "Sub-agent @#{nickname} spawned (session #{child.id}). " \
+      "Sub-agent #{nickname} spawned (session #{child.id}). " \
         "Its messages will appear in your conversation. " \
-        "Reply with @#{nickname} to send it instructions."
+        "To address it, prefix its name with @ in your message."
     end
 
     private
@@ -76,9 +81,10 @@ module Tools
       child = Session.create!(
         parent_session_id: @session.id,
         prompt: GENERIC_PROMPT,
-        granted_tools: granted_tools
+        granted_tools: granted_tools,
+        initial_cwd: @shell_session.pwd
       )
-      child.create_user_message(task)
+      create_goal_with_pinned_task(child, task)
       assign_nickname_via_brain(child)
       child.broadcast_children_update_to_parent
       AgentRequestJob.perform_later(child.id)