anima-core 1.0.2 → 1.1.1

data/lib/shell_session.rb

@@ -3,12 +3,20 @@
 require "io/console"
 require "pty"
 require "securerandom"
-require "timeout"
+require "shellwords"
 
 # Persistent shell session backed by a PTY with FIFO-based stderr separation.
 # Commands share working directory, environment variables, and shell history
 # within a conversation. Multiple tools share the same session.
 #
+# Auto-recovers from timeouts and crashes: if the shell dies, the next command
+# transparently respawns a fresh shell and restores the working directory.
+#
+# Uses IO.select-based deadlines instead of Timeout.timeout for all PTY reads.
+# Timeout.timeout is unsafe with PTY I/O — it uses Thread.raise which can
+# corrupt mutex state, leave resources inconsistent, and cause exceptions
+# to fire outside handler blocks when nested.
+#
 # @example
 #   session = ShellSession.new(session_id: 42)
 #   session.run("cd /tmp")
@@ -25,27 +33,39 @@ class ShellSession
     @mutex = Mutex.new
     @fifo_path = File.join(Dir.tmpdir, "anima-stderr-#{Process.pid}-#{SecureRandom.hex(8)}")
     @alive = false
+    @finalized = false
     @pwd = nil
+    @read_buffer = +""
     self.class.cleanup_orphans
     start
     self.class.register(self)
   end
 
-  # Execute a command in the persistent shell.
+  # Execute a command in the persistent shell. Respawns the shell
+  # automatically if the previous session died (timeout, crash, etc.).
   #
   # @param command [String] bash command to execute
+  # @param timeout [Integer, nil] per-call timeout in seconds; overrides
+  #   Settings.command_timeout when provided
   # @return [Hash] with :stdout, :stderr, :exit_code keys on success
   # @return [Hash] with :error key on failure
-  def run(command)
+  def run(command, timeout: nil)
     @mutex.synchronize do
-      return {error: "Shell session is not running"} unless @alive
-      execute_in_pty(command)
+      return {error: "Shell session is not running"} if @finalized
+      restart unless @alive
+      execute_in_pty(command, timeout: timeout)
     end
+  rescue => error # rubocop:disable Lint/RescueException -- LLM must always get a result hash, never a stack trace
+    {error: "#{error.class}: #{error.message}"}
   end
 
-  # Clean up PTY, FIFO, and child process.
+  # Clean up PTY, FIFO, and child process. Permanent — the session
+  # will not auto-respawn after this call.
   def finalize
-    @mutex.synchronize { shutdown }
+    @mutex.synchronize do
+      @finalized = true
+      teardown
+    end
     self.class.unregister(self)
   end
 
@@ -73,7 +93,7 @@ class ShellSession
     # Finalize all live sessions. Called automatically via at_exit.
     def cleanup_all
       @sessions_mutex.synchronize do
-        @sessions.each { |session| session.send(:shutdown) }
+        @sessions.each { |session| session.send(:teardown) }
         @sessions.clear
       end
     end
@@ -116,15 +136,54 @@ class ShellSession
     @alive = true
   end
 
+  # Shuts down the current shell and spawns a fresh one, restoring the
+  # previous working directory. Called automatically when @alive is false.
+  def restart
+    saved_pwd = @pwd
+    teardown
+    @fifo_path = File.join(Dir.tmpdir, "anima-stderr-#{Process.pid}-#{SecureRandom.hex(8)}")
+    start
+    restore_working_directory(saved_pwd)
+  end
+
+  # Restores the shell's working directory after a respawn.
+  # Skips silently if the directory no longer exists.
+  #
+  # @param saved_pwd [String, nil] directory path to restore
+  # @return [void]
+  def restore_working_directory(saved_pwd)
+    return unless saved_pwd && File.directory?(saved_pwd)
+    execute_in_pty("cd #{Shellwords.shellescape(saved_pwd)}")
+  end
+
   def create_fifo
-    File.mkfifo(@fifo_path)
+    File.mkfifo(@fifo_path, 0o600)
   rescue Errno::EEXIST
     # FIFO already exists — reuse it
   end
 
+  # Env vars that prevent interactive pagers and credential prompts from
+  # hanging the PTY. We need a PTY (not pipes) for pwd tracking via /proc
+  # and signal handling, but this makes programs think they're on a terminal
+  # and launch pagers. No single switch disables all pagers — each tool has
+  # its own env var — so we set a comprehensive list plus LESS flags as a
+  # safety net for direct `less` invocations.
+  SHELL_ENV = {
+    "TERM" => "dumb",
+    "PAGER" => "cat",                   # Default pager for most Unix tools
+    "LESS" => "-eFRX",                  # Safety net: make less auto-exit at EOF, no screen clear
+    "GIT_PAGER" => "cat",              # Git checks this before PAGER
+    "MANPAGER" => "cat",               # man pages
+    "SYSTEMD_PAGER" => "",             # journalctl, systemctl (empty = disable)
+    "BAT_PAGER" => "cat",             # bat (cat alternative)
+    "AWS_PAGER" => "",                 # AWS CLI v2 (empty = disable)
+    "PSQL_PAGER" => "cat",            # PostgreSQL psql
+    "GIT_TERMINAL_PROMPT" => "0"       # Fail immediately instead of prompting for credentials
+  }.freeze
+
   def spawn_shell
     @pty_stdout, @pty_stdin, @pid = PTY.spawn(
-      {"TERM" => "dumb"},
+      SHELL_ENV,
       "bash", "--norc", "--noprofile"
     )
     # Disable terminal echo via termios before bash can echo our commands.
@@ -165,45 +224,57 @@ class ShellSession
     @pty_stdin.puts "PS1=''"
     @pty_stdin.puts "exec 2>#{@fifo_path}"
     @pty_stdin.puts "echo '#{marker}'"
-    consume_until(marker)
+    unless consume_until(marker, deadline: monotonic_now + 10)
+      raise IOError, "Shell initialization timed out"
+    end
   end
 
-  def execute_in_pty(command)
+  def execute_in_pty(command, timeout: nil)
     clear_stderr
     marker = "__ANIMA_#{SecureRandom.hex(8)}__"
-    timeout = Anima::Settings.command_timeout
+    timeout ||= Anima::Settings.command_timeout
+    deadline = monotonic_now + timeout
 
-    Timeout.timeout(timeout) do
-      # All on one line: run command, capture exit code, ensure newline
-      # before marker so output without trailing newline doesn't merge.
-      @pty_stdin.puts "#{command}; __anima_ec=$?; echo; echo '#{marker}' $__anima_ec"
+    @pty_stdin.puts "#{command}; __anima_ec=$?; echo; echo '#{marker}' $__anima_ec"
 
-      stdout, exit_code = read_until_marker(marker)
-      update_pwd
-      stderr = drain_stderr
+    stdout, exit_code = read_until_marker(marker, deadline: deadline)
 
-      {
-        stdout: truncate(stdout),
-        stderr: truncate(stderr),
-        exit_code: exit_code
-      }
+    if exit_code.nil?
+      recover_from_timeout
+      stderr = drain_stderr
+      parts = ["Command timed out after #{timeout} seconds."]
+      parts << "Partial stdout:\n#{truncate(stdout)}" unless stdout.empty?
+      parts << "stderr:\n#{truncate(stderr)}" unless stderr.empty?
+      return {error: parts.join("\n\n")}
     end
-  rescue Timeout::Error
-    recover_from_timeout
-    {error: "Command timed out after #{timeout} seconds"}
-  rescue Errno::EIO
+
+    update_pwd
+    stderr = drain_stderr
+
+    {
+      stdout: truncate(stdout),
+      stderr: truncate(stderr),
+      exit_code: exit_code
+    }
+  rescue Errno::EIO, IOError
     @alive = false
     {error: "Shell session terminated unexpectedly"}
-  rescue => error
+  rescue => error # rubocop:disable Lint/RescueException -- LLM must always get a result hash, never a stack trace
     {error: "#{error.class}: #{error.message}"}
   end
 
-  def read_until_marker(marker)
+  # Reads lines from the PTY until the marker appears.
+  #
+  # @param marker [String] unique marker to detect command completion
+  # @param deadline [Float] monotonic clock deadline
+  # @return [Array(String, Integer)] stdout and exit code on success
+  # @return [Array(String, nil)] partial stdout and nil exit code on timeout
+  def read_until_marker(marker, deadline:)
     lines = []
     exit_code = nil
 
     loop do
-      line = @pty_stdout.gets
+      line = gets_with_deadline(deadline)
       break if line.nil?
 
       line = line.chomp.delete("\r")
@@ -219,26 +290,70 @@ class ShellSession
     # Strip trailing empty line added by our separator echo
     lines.pop if lines.last == ""
 
-    [lines.join("\n"), exit_code || -1]
+    [lines.join("\n"), exit_code]
   end
 
-  def consume_until(marker)
+  # Reads and discards PTY output until the marker appears or deadline expires.
+  #
+  # @param marker [String] unique marker to wait for
+  # @param deadline [Float] monotonic clock deadline
+  # @return [Boolean] true if marker was found, false if deadline expired
+  # @raise [Errno::EIO] when the PTY child process has exited
+  # @raise [IOError] when the PTY file descriptor is closed
+  def consume_until(marker, deadline:)
     loop do
-      line = @pty_stdout.gets
-      break if line.nil?
-      break if line.chomp.delete("\r").include?(marker)
+      line = gets_with_deadline(deadline)
+      return false if line.nil?
+      return true if line.chomp.delete("\r").include?(marker)
+    end
+  end
+
+  # Reads a single line from the PTY, respecting a deadline.
+  # Caller must hold @mutex — @read_buffer is not independently synchronized.
+  #
+  # Uses IO.select for safe, non-interruptive timeout handling instead of
+  # Timeout.timeout (which uses Thread.raise that can corrupt mutex state
+  # and leave resources inconsistent).
+  #
+  # @param deadline [Float] monotonic clock deadline
+  # @return [String] line including trailing newline
+  # @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)
+    loop do
+      if (idx = @read_buffer.index("\n"))
+        return @read_buffer.slice!(0..idx)
+      end
+
+      remaining = deadline - monotonic_now
+      return nil if remaining <= 0
+
+      ready = IO.select([@pty_stdout], nil, nil, remaining)
+      return nil unless ready
+
+      begin
+        @read_buffer << @pty_stdout.read_nonblock(4096)
+      rescue IO::WaitReadable
+        # Spurious wakeup from IO.select — retry
+      end
     end
   end
 
   # Sends Ctrl+C to interrupt the running command and drains leftover output.
-  # If recovery fails, marks the session as dead.
+  # 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
     @pty_stdin.write("\x03")
     sleep 0.1
     marker = "__ANIMA_RECOVER_#{SecureRandom.hex(8)}__"
     @pty_stdin.puts "echo '#{marker}'"
-    Timeout.timeout(3) { consume_until(marker) }
-  rescue Timeout::Error, Errno::EIO, IOError
+    recovered = consume_until(marker, deadline: monotonic_now + 3)
+    @alive = false unless recovered
+  rescue Errno::EIO, IOError
     @alive = false
   end
 
@@ -283,15 +398,26 @@ class ShellSession
       "\n\n[Truncated: output exceeded #{max_bytes} bytes]"
   end
 
-  def shutdown
-    return unless @alive
-    @alive = false
+  def monotonic_now
+    Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  end
 
-    begin
-      pgid = Process.getpgid(@pid)
-      Process.kill("TERM", -pgid)
-    rescue Errno::ESRCH, Errno::EPERM
-      # Process group already gone
+  # Unconditionally cleans up all shell resources (PTY, FIFO, child process).
+  # Does NOT short-circuit when @alive is already false — this ensures leaked
+  # processes are reaped even after failed recovery marked the session dead.
+  #
+  # @return [void]
+  def teardown
+    @alive = false
+    @read_buffer = +""
+
+    if @pid
+      begin
+        pgid = Process.getpgid(@pid)
+        Process.kill("TERM", -pgid)
+      rescue Errno::ESRCH, Errno::EPERM
+        # Process group already gone
+      end
     end
 
     begin
@@ -307,28 +433,33 @@ class ShellSession
     end
 
     begin
+      @stderr_thread&.join(1)
       @stderr_thread&.kill
     rescue ThreadError
       # Thread already dead
     end
 
-    File.delete(@fifo_path) if File.exist?(@fifo_path)
-
-    begin
-      # Non-blocking reap with SIGKILL fallback if process doesn't exit in time
-      deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + 2
-      loop do
-        _, status = Process.wait2(@pid, Process::WNOHANG)
-        break if status
-        if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
-          Process.kill("KILL", @pid)
-          Process.wait(@pid)
-          break
+    File.delete(@fifo_path) if @fifo_path && File.exist?(@fifo_path)
+
+    if @pid
+      begin
+        # Non-blocking reap with SIGKILL fallback if process doesn't exit in time
+        deadline = monotonic_now + 2
+        loop do
+          _, status = Process.wait2(@pid, Process::WNOHANG)
+          break if status
+          if monotonic_now > deadline
+            Process.kill("KILL", @pid)
+            Process.wait(@pid)
+            break
+          end
+          sleep 0.05
         end
-        sleep 0.05
+      rescue Errno::ECHILD, Errno::ESRCH
+        # Already reaped
       end
-    rescue Errno::ECHILD, Errno::ESRCH
-      # Already reaped
+
+      @pid = nil
     end
   end
 end

data/lib/tasks/fts5.rake

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# No custom Rake tasks needed — FTS5 virtual tables are handled by:
+# - Migration: creates/drops the FTS5 table and triggers
+# - Initializer (config/initializers/fts5_schema_dump.rb): skips virtual
+#   tables during schema dump since they can't be expressed in Ruby DSL

data/lib/tools/base.rb

@@ -49,7 +49,8 @@ module Tools
     def initialize(**) = nil
 
     # Execute the tool with the given input.
-    # @param input [Hash] parsed input matching {.input_schema}
+    # @param input [Hash] parsed input matching {.input_schema}. May include
+    #   a "timeout" key (seconds) for tools that support per-call timeout overrides.
     # @return [String, Hash] result content; Hash with :error key signals failure
     def execute(input)
       raise NotImplementedError, "#{self.class} must implement #execute"

data/lib/tools/bash.rb

@@ -27,14 +27,16 @@ module Tools
       @shell_session = shell_session
     end
 
-    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API.
+    #   Supports optional "timeout" key (seconds) to override the global
+    #   command_timeout setting for long-running operations.
     # @return [String] formatted output with stdout, stderr, and exit code
     # @return [Hash] with :error key on failure
     def execute(input)
       command = input["command"].to_s
       return {error: "Command cannot be blank"} if command.strip.empty?
 
-      result = @shell_session.run(command)
+      result = @shell_session.run(command, timeout: input["timeout"])
       return result if result.key?(:error)
 
       format_result(result[:stdout], result[:stderr], result[:exit_code])

data/lib/tools/registry.rb

@@ -30,16 +30,21 @@ module Tools
       @tools[tool.tool_name] = tool
     end
 
-    # @return [Array<Hash>] schema array for the Anthropic tools API parameter
+    # @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.
     def schemas
-      @tools.values.map(&:schema)
+      default = Anima::Settings.tool_timeout
+      @tools.values.map { |tool| inject_timeout(tool.schema, default) }
     end
 
     # Execute a tool by name. Classes are instantiated with the registry's
     # context; instances are called directly.
     #
     # @param name [String] registered tool name
-    # @param input [Hash] tool input parameters
+    # @param input [Hash] tool input parameters (may include "timeout" for
+    #   tools that support per-call timeout overrides)
     # @return [String, Hash] tool execution result
     # @raise [UnknownToolError] if no tool is registered with the given name
     def execute(name, input)
@@ -58,5 +63,19 @@ module Tools
     def any?
       @tools.any?
     end
+
+    private
+
+    # 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"] = {
+        type: "integer",
+        description: "Max execution seconds (default: #{default}). Increase for long-running operations."
+      }
+      s
+    end
   end
 end

data/lib/tools/remember.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module Tools
+  # Fractal-resolution zoom into event history. Returns a window centered
+  # on a target event with full detail at the center and compressed context
+  # at the edges — sharp fovea, blurry periphery.
+  #
+  # Output structure:
+  #   [Previous snapshots — compressed context before]
+  #   [Events N-M — full detail, tool_responses compressed to checkmarks]
+  #   [Following snapshots — compressed context after]
+  #
+  # The agent discovers target events via FTS5 search results embedded in
+  # viewport recall snippets. This tool drills down into the full context.
+  #
+  # @example
+  #   remember(event_id: 42)
+  class Remember < Base
+    # Events around the target to include at full resolution.
+    # ±10 events provides sharp foveal detail while keeping output readable.
+    CONTEXT_WINDOW = 20
+
+    ROLE_LABELS = {
+      "user_message" => "User",
+      "agent_message" => "Assistant",
+      "system_message" => "System"
+    }.freeze
+
+    def self.tool_name = "remember"
+
+    def self.description
+      "Recall the full context around a past event. " \
+        "Returns a fractal-resolution window: high detail at the center " \
+        "(the target event and its neighbors), compressed context at the edges " \
+        "(snapshots before and after). Use this when search results surface " \
+        "a relevant event and you need the surrounding conversation."
+    end
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          event_id: {
+            type: "integer",
+            description: "The event ID to zoom into (from search results or recall snippets)"
+          }
+        },
+        required: ["event_id"]
+      }
+    end
+
+    def initialize(session:, **)
+      @session = session
+    end
+
+    # @param input [Hash] with "event_id"
+    # @return [String] fractal-resolution window around the target event
+    def execute(input)
+      event_id = input["event_id"].to_i
+      target = Event.find_by(id: event_id)
+      return {error: "Event #{event_id} not found"} unless target
+
+      build_fractal_window(target)
+    end
+
+    private
+
+    # Assembles the three-zone fractal window.
+    #
+    # @param target [Event] the center event
+    # @return [String] formatted fractal window
+    def build_fractal_window(target)
+      target_session = target.session
+      center_events = fetch_center_events(target, target_session)
+      first_center_id = center_events.first&.id
+      last_center_id = center_events.last&.id
+
+      sections = build_sections(
+        target_session: target_session,
+        center_events: center_events,
+        target_id: target.id,
+        first_center_id: first_center_id,
+        last_center_id: last_center_id
+      )
+      sections.join("\n")
+    end
+
+    # Builds ordered sections: header, before snapshots, center, after snapshots.
+    def build_sections(target_session:, center_events:, target_id:, first_center_id:, last_center_id:)
+      sections = [session_header(target_session)]
+
+      append_snapshot_sections(sections, target_session.snapshots
+        .where("to_event_id < ?", first_center_id)
+        .chronological.last(3), label: "PREVIOUS CONTEXT")
+
+      sections << "── FULL CONTEXT (events #{first_center_id}..#{last_center_id}) ──"
+      center_events.each { |event| sections << render_center_event(event, target_id) }
+
+      append_snapshot_sections(sections, target_session.snapshots
+        .where("from_event_id > ?", last_center_id)
+        .chronological.first(3), label: "FOLLOWING CONTEXT")
+
+      sections
+    end
+
+    def session_header(target_session)
+      label = target_session.name || "Session ##{target_session.id}"
+      "── recalled from: #{label} ──"
+    end
+
+    # Appends snapshot sections if any exist.
+    def append_snapshot_sections(sections, snapshots, label:)
+      return if snapshots.empty?
+
+      sections << "── #{label} (compressed) ──"
+      snapshots.each { |snapshot| sections << format_snapshot(snapshot) }
+    end
+
+    # Fetches conversation events around the target within a fixed window.
+    #
+    # @return [Array<Event>] chronologically ordered
+    def fetch_center_events(target, target_session)
+      half = CONTEXT_WINDOW / 2
+      scope = target_session.events.context_events.deliverable
+      target_id = target.id
+
+      before = scope.where("id <= ?", target_id).reorder(id: :desc).limit(half + 1).to_a.reverse
+      after = scope.where("id > ?", target_id).reorder(id: :asc).limit(half).to_a
+
+      before + after
+    end
+
+    # Renders a center event at full resolution.
+    # Conversation events show full content. Tool calls show name + input.
+    # Tool responses compressed to status indicator.
+    #
+    # @param event [Event]
+    # @param target_id [Integer] the event being zoomed into (marked with arrow)
+    # @return [String]
+    def render_center_event(event, target_id)
+      marker = (event.id == target_id) ? "→" : " "
+      prefix = "#{marker} event #{event.id}"
+
+      "#{prefix} #{format_event_content(event)}"
+    end
+
+    # Formats event content based on type.
+    def format_event_content(event)
+      data = event.payload
+      content = data["content"]
+
+      if ROLE_LABELS.key?(event.event_type)
+        "#{ROLE_LABELS[event.event_type]}: #{content}"
+      elsif event.event_type == "tool_call"
+        format_tool_call(data)
+      elsif event.event_type == "tool_response"
+        status = content.to_s.start_with?("Error") ? "error" : "ok"
+        "ToolResult: [#{status}] #{data["tool_use_id"]}"
+      end
+    end
+
+    def format_tool_call(data)
+      if data["tool_name"] == Event::THINK_TOOL
+        "Think: #{data.dig("tool_input", "thoughts")}"
+      else
+        "Tool: #{data["tool_name"]}(#{data["tool_input"].to_json.truncate(200)})"
+      end
+    end
+
+    # Formats a snapshot as compressed context.
+    #
+    # @param snapshot [Snapshot]
+    # @return [String]
+    def format_snapshot(snapshot)
+      level = (snapshot.level == 2) ? "L2" : "L1"
+      "[#{level} snapshot, events #{snapshot.from_event_id}..#{snapshot.to_event_id}]\n#{snapshot.text}"
+    end
+  end
+end

data/lib/tools/request_feature.rb

@@ -71,7 +71,9 @@ module Tools
 
     # @return [String, nil] owner/repo parsed from +git remote get-url origin+
     def git_remote_repo
-      url, _status = Open3.capture2("git", "remote", "get-url", "origin")
+      url, status = Open3.capture2("git", "remote", "get-url", "origin", err: File::NULL)
+      return unless status.success?
+
       parse_owner_repo(url.strip)
     rescue Errno::ENOENT
       nil