anima-core 1.3.0 → 1.5.0

data/lib/environment_probe.rb

@@ -1,232 +0,0 @@
-# frozen_string_literal: true
-
-require "etc"
-require "open3"
-require "timeout"
-require "json"
-require "pathname"
-require "uri"
-
-# Probes the shell environment and assembles a lightweight metadata block
-# for injection into the system prompt. Gives the agent awareness of its
-# working directory, OS, Git status, and nearby project files — without
-# loading any file content.
-#
-# @example
-#   EnvironmentProbe.to_prompt("/home/user/projects/my-app")
-#   # => "## Environment\n\nOS: Arch Linux (pacman, yay)\n..."
-class EnvironmentProbe
-  # Assembles the environment context block for a given working directory.
-  #
-  # @param pwd [String, nil] current working directory
-  # @return [String, nil] Markdown-formatted environment block, or nil when pwd is unknown
-  def self.to_prompt(pwd)
-    new(pwd).to_prompt
-  end
-
-  # @param pwd [String, nil] current working directory
-  def initialize(pwd)
-    @pwd = pwd
-  end
-
-  # @return [String, nil] Markdown-formatted environment block
-  def to_prompt
-    return unless @pwd
-
-    sections = [os_section, working_directory_section, project_files_section].compact
-    return if sections.empty?
-
-    "## Environment\n\n#{sections.join("\n\n")}"
-  end
-
-  private
-
-  # @return [String] OS name with package manager hint
-  def os_section
-    sysname = Etc.uname[:sysname]
-    "OS: #{format_os(sysname)}"
-  end
-
-  # @param sysname [String] kernel name from uname (e.g. "Linux", "Darwin")
-  # @return [String] human-readable OS description
-  def format_os(sysname)
-    case sysname
-    when "Linux"
-      distro = detect_linux_distro || "Linux"
-      pkg = detect_package_manager
-      pkg ? "#{distro} (#{pkg})" : distro
-    when "Darwin"
-      "macOS (Homebrew)"
-    else
-      sysname
-    end
-  end
-
-  # Reads PRETTY_NAME from /etc/os-release.
-  #
-  # @return [String, nil] distro name, or nil on non-Linux / missing file
-  def detect_linux_distro
-    return unless File.exist?("/etc/os-release")
-
-    File.foreach("/etc/os-release") do |line|
-      if line.start_with?("PRETTY_NAME=")
-        return line.split("=", 2).last.strip.delete('"')
-      end
-    end
-    nil
-  end
-
-  # Returns the primary package manager(s) for the current system.
-  # Arch-based systems list both pacman and yay when present;
-  # other families return the first match.
-  #
-  # @return [String, nil] comma-separated package manager names
-  def detect_package_manager
-    managers = []
-    managers << "pacman" if File.exist?("/usr/bin/pacman")
-    managers << "yay" if File.exist?("/usr/bin/yay")
-    return managers.join(", ") if managers.any?
-
-    return "apt" if File.exist?("/usr/bin/apt")
-    return "dnf" if File.exist?("/usr/bin/dnf")
-    return "Homebrew" if File.exist?("/opt/homebrew/bin/brew") || File.exist?("/usr/local/bin/brew")
-
-    nil
-  end
-
-  # @return [String] CWD line plus optional Git metadata
-  def working_directory_section
-    lines = ["CWD: #{@pwd}"]
-    append_git_lines(lines)
-    lines.join("\n")
-  end
-
-  # Appends Git metadata lines (remote, branch, PR) to the output array.
-  #
-  # @param lines [Array<String>] accumulator for output lines
-  # @return [void]
-  def append_git_lines(lines)
-    git = detect_git
-    return unless git
-
-    remote = git[:remote]
-    branch = git[:branch]
-    pr_number = git[:pr_number]
-
-    lines << "Git: #{git[:repo_name]} (#{remote})" if remote
-    lines << "Branch: #{branch}" if branch
-    lines << "PR: ##{pr_number} (#{git[:pr_state]})" if pr_number
-  end
-
-  # Detects Git repo metadata: remote, branch, and open PR.
-  #
-  # @return [Hash{Symbol => String}, nil] keys: :remote, :repo_name, :branch,
-  #   and optionally :pr_number (Integer) and :pr_state (String); nil when not in a repo
-  def detect_git
-    _, status = Open3.capture2("git", "-C", @pwd, "rev-parse", "--is-inside-work-tree", err: File::NULL)
-    return unless status.success?
-
-    info = {}
-    detect_git_remote(info)
-    detect_git_branch(info)
-    info
-  rescue Errno::ENOENT
-    nil
-  end
-
-  # Populates :remote and :repo_name on the info hash.
-  def detect_git_remote(info)
-    remote, = Open3.capture2("git", "-C", @pwd, "remote", "get-url", "origin", err: File::NULL)
-    remote = remote.strip
-    return unless remote.present?
-
-    info[:remote] = remote
-    info[:repo_name] = extract_repo_name(remote)
-  end
-
-  # Populates :branch, :pr_number, and :pr_state on the info hash.
-  def detect_git_branch(info)
-    branch, = Open3.capture2("git", "-C", @pwd, "rev-parse", "--abbrev-ref", "HEAD", err: File::NULL)
-    branch = branch.strip
-    return unless branch.present?
-
-    info[:branch] = branch
-    pr = detect_pr(branch)
-    info.merge!(pr) if pr
-  end
-
-  # Extracts owner/repo from a Git remote URL.
-  #
-  # @param remote_url [String] SSH or HTTPS remote URL
-  # @return [String] "owner/repo" path, or the raw URL when parsing fails
-  def extract_repo_name(remote_url)
-    path = if remote_url.match?(%r{\A\w+://})
-      URI.parse(remote_url).path
-    else
-      # SSH format: git@host:owner/repo.git
-      remote_url.split(":").last
-    end
-    path.delete_prefix("/").delete_suffix(".git")
-  rescue URI::InvalidURIError
-    remote_url
-  end
-
-  # Queries GitHub for an open PR on the given branch via the gh CLI.
-  #
-  # @param branch [String] branch name
-  # @return [Hash, nil] with :pr_number and :pr_state, or nil
-  # @note Returns nil on timeout, missing gh CLI, or JSON parse errors
-  def detect_pr(branch)
-    Timeout.timeout(Anima::Settings.web_request_timeout) do
-      output, status = Open3.capture2(
-        "gh", "pr", "list", "--head", branch,
-        "--json", "number,state", "--limit", "1",
-        chdir: @pwd, err: File::NULL
-      )
-      return unless status.success?
-
-      pr = JSON.parse(output).first
-      return unless pr
-
-      {pr_number: pr["number"], pr_state: pr["state"].downcase}
-    end
-  rescue Timeout::Error, Errno::ENOENT, JSON::ParserError
-    nil
-  end
-
-  # Scans for well-known project files up to a configurable depth.
-  #
-  # @return [String, nil] project files section, or nil when none found
-  def project_files_section
-    found = scan_project_files
-    return if found.empty?
-
-    header = "Project files that may contain useful context:"
-    entries = found.map { |path| "- #{path}" }
-    [header, *entries, "Use read_file to examine these when needed."].join("\n")
-  end
-
-  # Scans the working directory for whitelisted filenames.
-  #
-  # @return [Array<String>] sorted relative paths
-  def scan_project_files
-    base = Pathname.new(@pwd)
-
-    glob_patterns.flat_map { |pattern| Dir.glob(pattern) }
-      .map { |full_path| Pathname.new(full_path).relative_path_from(base).to_s }
-      .sort
-      .uniq
-  end
-
-  # Builds glob patterns for each whitelisted filename at each depth level.
-  #
-  # @return [Array<String>] glob patterns
-  def glob_patterns
-    whitelist = Anima::Settings.project_files_whitelist
-    max_depth = Anima::Settings.project_files_max_depth
-
-    whitelist.product((0..max_depth).to_a).map do |filename, depth|
-      File.join(@pwd, Array.new(depth, "*"), filename)
-    end
-  end
-end

data/lib/events/agent_message.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module Events
-  class AgentMessage < Base
-    TYPE = "agent_message"
-
-    def type
-      TYPE
-    end
-  end
-end

data/lib/events/subscribers/message_collector.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-module Events
-  module Subscribers
-    # Collects chat-displayable events in-memory for the current session.
-    # Provides the message list that the TUI renders and the LLM client consumes.
-    #
-    # Only user_message and agent_message events are collected — system_message,
-    # tool_call, and tool_response are internal and not part of the chat display.
-    #
-    # @example
-    #   collector = Events::Subscribers::MessageCollector.new
-    #   Events::Bus.subscribe(collector)
-    #   collector.messages # => [{role: "user", content: "hi"}, ...]
-    class MessageCollector
-      include Events::Subscriber
-
-      DISPLAYABLE_TYPES = %w[user_message agent_message].freeze
-
-      # Maps event types to LLM-compatible role identifiers
-      ROLE_MAP = {
-        "user_message" => "user",
-        "agent_message" => "assistant"
-      }.freeze
-
-      def initialize
-        @messages = []
-        @mutex = Mutex.new
-      end
-
-      # @return [Array<Hash>] thread-safe copy of collected messages
-      def messages
-        @mutex.synchronize { @messages.dup }
-      end
-
-      # Receives a Rails.event notification hash.
-      # @param event [Hash] with :payload containing :type and :content keys
-      def emit(event)
-        type = event.dig(:payload, :type)
-        return unless DISPLAYABLE_TYPES.include?(type)
-
-        content = event.dig(:payload, :content)
-        return if content.nil?
-
-        @mutex.synchronize do
-          @messages << {
-            role: ROLE_MAP.fetch(type),
-            content: content
-          }
-        end
-      end
-
-      # Directly push a pre-built message hash (used for loading persisted events).
-      # @param message [Hash] with :role and :content keys
-      def messages_push(message)
-        @mutex.synchronize { @messages << message }
-      end
-
-      def clear
-        @mutex.synchronize { @messages = [] }
-      end
-    end
-  end
-end

data/lib/events/tool_call.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Events
-  class ToolCall < Base
-    TYPE = "tool_call"
-
-    attr_reader :tool_name, :tool_input, :tool_use_id, :timeout
-
-    # @param content [String] human-readable description of the tool call
-    # @param tool_name [String] registered tool name (e.g. "web_get")
-    # @param tool_input [Hash] arguments passed to the tool
-    # @param tool_use_id [String] Anthropic-assigned ID for correlating call/result
-    # @param timeout [Integer] maximum seconds before the call is considered orphaned
-    # @param session_id [String, nil] optional session identifier
-    def initialize(content:, tool_name:, tool_input: {}, tool_use_id: nil, timeout: nil, session_id: nil)
-      super(content: content, session_id: session_id)
-      @tool_name = tool_name
-      @tool_input = tool_input
-      @tool_use_id = tool_use_id
-      @timeout = timeout
-    end
-
-    def type
-      TYPE
-    end
-
-    def to_h
-      super.merge(tool_name: tool_name, tool_input: tool_input, tool_use_id: tool_use_id, timeout: timeout)
-    end
-  end
-end

data/lib/events/tool_response.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Events
-  class ToolResponse < Base
-    TYPE = "tool_response"
-
-    attr_reader :tool_name, :success, :tool_use_id
-
-    # @param content [String] tool execution output
-    # @param tool_name [String] registered tool name
-    # @param success [Boolean] whether the tool executed successfully
-    # @param tool_use_id [String, nil] Anthropic-assigned ID for correlating call/result
-    # @param session_id [String, nil] optional session identifier
-    def initialize(content:, tool_name:, success: true, tool_use_id: nil, session_id: nil)
-      super(content: content, session_id: session_id)
-      @tool_name = tool_name
-      @success = success
-      @tool_use_id = tool_use_id
-    end
-
-    def type
-      TYPE
-    end
-
-    def success?
-      @success
-    end
-
-    def to_h
-      super.merge(tool_name: tool_name, success: success, tool_use_id: tool_use_id)
-    end
-  end
-end

data/lib/mneme/compressed_viewport.rb

@@ -1,200 +0,0 @@
-# frozen_string_literal: true
-
-module Mneme
-  # Builds a compressed viewport for Mneme's LLM context. Mneme sees
-  # conversation (user/agent messages and think events) but not mechanical
-  # execution (tool calls and responses). Tool calls are compressed to
-  # aggregate counters like `[4 tools called]`.
-  #
-  # The viewport is split into three zones separated by delimiters:
-  # - **Eviction zone** — messages about to leave the viewport (upper third)
-  # - **Middle zone** — messages in the middle of the viewport
-  # - **Recent zone** — the most recent messages (lower third)
-  #
-  # Zone boundaries are calculated WITH tool call tokens (they affect
-  # position), then tool calls are removed and replaced with counters.
-  #
-  # @example
-  #   viewport = Mneme::CompressedViewport.new(session, token_budget: 60_000)
-  #   viewport.render  #=> "── EVICTION ZONE ──\nmessage 42 User: ..."
-  class CompressedViewport
-    ZONE_DELIMITERS = {
-      eviction: "── EVICTION ZONE (upper third) ──",
-      middle: "── MIDDLE ZONE ──",
-      recent: "── RECENT ZONE (lower third) ──"
-    }.freeze
-
-    # @param session [Session] the session to build viewport for
-    # @param token_budget [Integer] total tokens available for Mneme's viewport
-    # @param from_message_id [Integer, nil] start from this message ID (inclusive);
-    #   when nil, uses the session's full viewport
-    def initialize(session, token_budget:, from_message_id: nil)
-      @session = session
-      @token_budget = token_budget
-      @from_message_id = from_message_id
-    end
-
-    # Renders the compressed viewport as a string ready for Mneme's LLM context.
-    #
-    # @return [String] compressed viewport with zone delimiters
-    def render
-      return "" if messages.empty?
-
-      zones = split_into_zones(messages)
-      render_zones(zones)
-    end
-
-    # @return [Array<Message>] the raw messages selected for this viewport
-    def messages
-      @messages ||= fetch_messages
-    end
-
-    private
-
-    # Fetches messages within token budget, starting from from_message_id.
-    # Selects newest-first until budget exhausted, returns chronological.
-    # Caches per-message token costs in @message_costs for reuse by split_into_zones.
-    #
-    # @return [Array<Message>]
-    def fetch_messages
-      scope = @session.messages.context_messages
-
-      if @from_message_id
-        scope = scope.where("id >= ?", @from_message_id)
-      end
-
-      selected = []
-      @message_costs = {}
-      remaining = @token_budget
-
-      scope.reorder(id: :desc).each do |message|
-        cost = message_token_cost(message)
-        break if cost > remaining && selected.any?
-
-        selected << message
-        @message_costs[message.id] = cost
-        remaining -= cost
-      end
-
-      selected.reverse
-    end
-
-    # Splits messages into three zones by token count.
-    # Zone boundaries are calculated including ALL messages (tool calls count
-    # toward position), but zone assignment uses cumulative tokens.
-    #
-    # @return [Hash{Symbol => Array<Message>}] :eviction, :middle, :recent
-    def split_into_zones(messages)
-      costs = messages.map { |message| [message, @message_costs[message.id] || message_token_cost(message)] }
-      zone_size = costs.sum(&:last) / 3.0
-
-      result = {eviction: [], middle: [], recent: []}
-      cumulative = 0
-
-      costs.each do |message, cost|
-        cumulative += cost
-        result[zone_for_cumulative(cumulative, zone_size)] << message
-      end
-
-      result
-    end
-
-    # Renders zones with delimiters, compressing tool calls into counters.
-    #
-    # @param zones [Hash{Symbol => Array<Message>}]
-    # @return [String]
-    def render_zones(zones)
-      %i[eviction middle recent].flat_map { |name|
-        [ZONE_DELIMITERS[name], render_zone(zones[name])]
-      }.join("\n")
-    end
-
-    # Determines which zone an event belongs to based on cumulative token position.
-    #
-    # @param cumulative [Numeric] cumulative token count including this event
-    # @param zone_size [Float] token count per zone (total / 3)
-    # @return [Symbol] :eviction, :middle, or :recent
-    def zone_for_cumulative(cumulative, zone_size)
-      if cumulative <= zone_size
-        :eviction
-      elsif cumulative <= zone_size * 2
-        :middle
-      else
-        :recent
-      end
-    end
-
-    # Renders a single zone: conversation messages as full text, consecutive
-    # tool calls/responses compressed into `[N tools called]` counters.
-    # tool_response messages are intentionally silent — they affect zone boundaries
-    # via token cost but are not rendered; only tool_call messages increment the counter.
-    #
-    # @param zone_messages [Array<Message>]
-    # @return [String]
-    def render_zone(zone_messages)
-      lines = []
-      tool_count = 0
-
-      zone_messages.each do |message|
-        if conversation_message?(message) || think_message?(message)
-          lines << flush_tool_count(tool_count)
-          tool_count = 0
-          lines << render_message_line(message)
-        elsif message.message_type == "tool_call"
-          tool_count += 1
-        end
-      end
-
-      lines << flush_tool_count(tool_count)
-      lines.compact.join("\n")
-    end
-
-    # @return [Boolean] true if message is a user/agent/system message
-    def conversation_message?(message)
-      message.message_type.in?(Message::CONVERSATION_TYPES)
-    end
-
-    # Think messages are tool_call messages with tool_name == "think".
-    # They carry the agent's reasoning and are treated as conversation.
-    #
-    # @return [Boolean]
-    def think_message?(message)
-      message.message_type == "tool_call" && message.payload["tool_name"] == Message::THINK_TOOL
-    end
-
-    ROLE_LABELS = {
-      "user_message" => "User",
-      "agent_message" => "Assistant",
-      "system_message" => "System"
-    }.freeze
-
-    # Renders a single message as a transcript line.
-    #
-    # @param message [Message]
-    # @return [String]
-    def render_message_line(message)
-      prefix = "message #{message.id}"
-      data = message.payload
-      if think_message?(message)
-        "#{prefix} Think: #{data.dig("tool_input", "thoughts")}"
-      else
-        "#{prefix} #{ROLE_LABELS.fetch(message.message_type)}: #{data["content"]}"
-      end
-    end
-
-    # Returns a tool count string if any tools were called, nil otherwise.
-    #
-    # @param count [Integer] number of tool calls to flush
-    # @return [String, nil]
-    def flush_tool_count(count)
-      return if count == 0
-      "[#{count} #{(count == 1) ? "tool" : "tools"} called]"
-    end
-
-    # @return [Integer] token cost using cached count or heuristic
-    def message_token_cost(message)
-      cached = message.token_count
-      (cached > 0) ? cached : message.estimate_tokens
-    end
-  end
-end

data/lib/mneme/passive_recall.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-module Mneme
-  # Passive recall — automatic memory surfacing triggered by Goal updates.
-  # When goals are created or updated, searches event history for related
-  # context and caches the results on the session for viewport injection.
-  #
-  # The agent never calls a tool; relevant memories appear automatically
-  # in the viewport between snapshots and the sliding window. This mirrors
-  # recognition memory in humans — context surfaces without conscious effort.
-  #
-  # @example Trigger after a goal update
-  #   Mneme::PassiveRecall.new(session).call
-  class PassiveRecall
-    # @param session [Session] the session whose goals drive recall
-    def initialize(session)
-      @session = session
-    end
-
-    # Searches event history using active goal descriptions as queries.
-    # Returns recall results suitable for viewport injection.
-    #
-    # @return [Array<Mneme::Search::Result>] deduplicated, relevance-sorted
-    def call
-      goals = @session.goals.active.root.includes(:sub_goals)
-      return [] if goals.empty?
-
-      search_terms = build_search_terms(goals)
-      return [] if search_terms.blank?
-
-      results = Mneme::Search.query(search_terms, limit: Anima::Settings.recall_max_results)
-
-      # Exclude events from the current session's viewport — no point recalling
-      # what the agent already sees.
-      viewport_ids = @session.viewport_message_ids.to_set
-      results.reject { |result| viewport_ids.include?(result.message_id) }
-    end
-
-    private
-
-    STOP_WORDS = Set.new(%w[
-      a an the is are was were be been being do does did
-      have has had in on at to for of and or but not with
-      this that it its by from as up out if about into
-      fix add create update remove implement check set get
-    ]).freeze
-
-    # Extracts meaningful keywords from active goals and joins with OR.
-    # Stop words and generic verbs are stripped — they're too common to
-    # produce useful recall results.
-    #
-    # @param goals [ActiveRecord::Relation<Goal>]
-    # @return [String] FTS5 OR-joined keywords
-    def build_search_terms(goals)
-      descriptions = goals.flat_map { |goal|
-        [goal.description] + goal.sub_goals.reject(&:completed?).map(&:description)
-      }
-
-      words = descriptions.join(" ")
-        .gsub(/[^a-zA-Z0-9\s-]/, "")
-        .downcase
-        .split
-        .uniq
-        .reject { |word| STOP_WORDS.include?(word) || word.length < 3 }
-
-      words.join(" OR ").truncate(500)
-    end
-  end
-end