anima-core 1.0.2 → 1.1.1

data/lib/mneme/search.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Mneme
+  # Full-text search over event history using SQLite FTS5.
+  # Covers user messages, agent messages, and think events across all sessions.
+  #
+  # The interface is intentionally abstract — callers receive {Result} structs
+  # and never touch FTS5 directly. A future semantic search backend (embeddings,
+  # BM25 + re-ranking) can replace the implementation without changing callers.
+  #
+  # @example Search across all sessions
+  #   results = Mneme::Search.query("authentication flow")
+  #   results.each { |r| puts "event #{r.event_id}: #{r.snippet}" }
+  #
+  # @example Search within a single session
+  #   results = Mneme::Search.query("OAuth config", session_id: 42)
+  class Search
+    # A single search result with enough context for display and drill-down.
+    #
+    # @!attribute event_id [Integer] the event's database ID
+    # @!attribute session_id [Integer] the session owning this event
+    # @!attribute snippet [String] highlighted excerpt from the matching content
+    # @!attribute rank [Float] FTS5 relevance score (lower = more relevant)
+    # @!attribute event_type [String] one of Event::TYPES
+    Result = Struct.new(:event_id, :session_id, :snippet, :rank, :event_type, keyword_init: true)
+
+    # Searches event history for the given terms.
+    #
+    # @param terms [String] search query (FTS5 syntax: words, phrases, OR/AND/NOT)
+    # @param session_id [Integer, nil] scope to a specific session (nil = all sessions)
+    # @param limit [Integer] maximum results
+    # @return [Array<Result>] ranked by relevance (best first)
+    def self.query(terms, session_id: nil, limit: Anima::Settings.recall_max_results)
+      new(terms, session_id: session_id, limit: limit).call
+    end
+
+    def initialize(terms, session_id: nil, limit: 5)
+      @terms = sanitize_query(terms)
+      @session_id = session_id
+      @limit = limit
+    end
+
+    # @return [Array<Result>] ranked by relevance (best first)
+    def call
+      return [] if @terms.blank?
+
+      rows = execute_fts_query
+      rows.map { |row| build_result(row) }
+    end
+
+    private
+
+    # Executes the FTS5 MATCH query with optional session scoping.
+    # Joins back to events table for session_id and event_type.
+    #
+    # @return [Array<Hash>] raw database rows
+    def execute_fts_query
+      if @session_id
+        connection.select_all(scoped_sql, "Mneme::Search", [@terms, @session_id, @limit]).to_a
+      else
+        connection.select_all(global_sql, "Mneme::Search", [@terms, @limit]).to_a
+      end
+    end
+
+    # FTS5 query across all sessions.
+    # Contentless FTS5 can't use snippet() — extract content from events directly.
+    def global_sql
+      <<~SQL
+        SELECT
+          e.id AS event_id,
+          e.session_id,
+          e.event_type,
+          CASE
+            WHEN e.event_type IN ('user_message', 'agent_message', 'system_message')
+              THEN substr(json_extract(e.payload, '$.content'), 1, 300)
+            WHEN e.event_type = 'tool_call'
+              THEN substr(json_extract(e.payload, '$.tool_input.thoughts'), 1, 300)
+          END AS snippet,
+          rank
+        FROM events_fts
+        JOIN events e ON e.id = events_fts.rowid
+        WHERE events_fts MATCH ?
+        ORDER BY rank
+        LIMIT ?
+      SQL
+    end
+
+    # FTS5 query scoped to a specific session.
+    def scoped_sql
+      <<~SQL
+        SELECT
+          e.id AS event_id,
+          e.session_id,
+          e.event_type,
+          CASE
+            WHEN e.event_type IN ('user_message', 'agent_message', 'system_message')
+              THEN substr(json_extract(e.payload, '$.content'), 1, 300)
+            WHEN e.event_type = 'tool_call'
+              THEN substr(json_extract(e.payload, '$.tool_input.thoughts'), 1, 300)
+          END AS snippet,
+          rank
+        FROM events_fts
+        JOIN events e ON e.id = events_fts.rowid
+        WHERE events_fts MATCH ?
+          AND e.session_id = ?
+        ORDER BY rank
+        LIMIT ?
+      SQL
+    end
+
+    # Builds a Result from a raw database row.
+    #
+    # @param row [Hash]
+    # @return [Result]
+    def build_result(row)
+      Result.new(
+        event_id: row["event_id"],
+        session_id: row["session_id"],
+        snippet: row["snippet"],
+        rank: row["rank"],
+        event_type: row["event_type"]
+      )
+    end
+
+    # Sanitizes user input for FTS5 MATCH safety.
+    # Strips special FTS5 operators that could cause syntax errors,
+    # keeps only alphanumeric words and quoted phrases.
+    #
+    # @param raw [String]
+    # @return [String] safe FTS5 query
+    def sanitize_query(raw)
+      return "" unless raw
+
+      # Extract quoted phrases and individual words, drop FTS5 operators
+      tokens = raw.scan(/"[^"]+?"|\S+/).reject { |token| token.match?(/\A[*:^{}()]+\z/) }
+      tokens.filter_map { |token| sanitize_token(token) }.join(" ")
+    end
+
+    def sanitize_token(token)
+      return token if token.start_with?('"')
+
+      cleaned = token.gsub(/[^a-zA-Z0-9-]/, "")
+      cleaned.empty? ? nil : cleaned
+    end
+
+    def connection
+      ActiveRecord::Base.connection
+    end
+  end
+end

data/lib/mneme/tools/attach_events_to_goals.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Mneme
+  module Tools
+    # Pins critical events to active Goals so they survive viewport eviction.
+    # Mneme calls this when it sees important events (user instructions, key
+    # decisions, critical corrections) approaching the eviction zone.
+    #
+    # Events are pinned via a many-to-many join: one event can be attached
+    # to multiple Goals. When all referencing Goals complete, the pin is
+    # automatically released (reference-counted cleanup in {Goal#release_orphaned_pins!}).
+    class AttachEventsToGoals < ::Tools::Base
+      def self.tool_name = "attach_events_to_goals"
+
+      def self.description = "Pin critical events to active goals so they survive " \
+        "viewport eviction. Use this for events that are too important to lose — " \
+        "exact user instructions, key decisions, critical corrections. " \
+        "Events stay pinned until all attached goals complete."
+
+      def self.input_schema
+        {
+          type: "object",
+          properties: {
+            event_ids: {
+              type: "array",
+              items: {type: "integer"},
+              description: "Database IDs of events to pin (from `event N` prefixes in the viewport)"
+            },
+            goal_ids: {
+              type: "array",
+              items: {type: "integer"},
+              description: "IDs of active goals to attach the events to"
+            }
+          },
+          required: %w[event_ids goal_ids]
+        }
+      end
+
+      # @param main_session [Session] the session being observed
+      def initialize(main_session:, **)
+        @session = main_session
+      end
+
+      # @param input [Hash<String, Object>] with "event_ids" and "goal_ids"
+      # @return [String] confirmation with link count, or error description
+      def execute(input)
+        event_ids = Array(input["event_ids"]).map(&:to_i).uniq
+        goal_ids = Array(input["goal_ids"]).map(&:to_i).uniq
+
+        return "Error: event_ids cannot be empty" if event_ids.empty?
+        return "Error: goal_ids cannot be empty" if goal_ids.empty?
+
+        events = @session.events.where(id: event_ids)
+        goals = @session.goals.active.where(id: goal_ids)
+
+        missing_events = event_ids - events.pluck(:id)
+        inactive_goal_ids = goal_ids - goals.pluck(:id)
+
+        errors = []
+        errors << "Events not found: #{missing_events.join(", ")}" if missing_events.any?
+
+        if inactive_goal_ids.any?
+          completed_ids = @session.goals.completed.where(id: inactive_goal_ids).pluck(:id)
+          not_found_ids = inactive_goal_ids - completed_ids
+          errors << "Goals already completed: #{completed_ids.join(", ")}" if completed_ids.any?
+          errors << "Goals not found: #{not_found_ids.join(", ")}" if not_found_ids.any?
+        end
+
+        return "Error: #{errors.join("; ")}" if errors.any?
+
+        attached = attach(events, goals)
+        "Pinned #{attached} event-goal links"
+      end
+
+      private
+
+      def attach(events, goals)
+        events.sum do |event|
+          pinned = find_or_create_pinned_event(event)
+          link_to_goals(pinned, goals)
+        end
+      end
+
+      def link_to_goals(pinned, goals)
+        goals.each { |goal| GoalPinnedEvent.find_or_create_by!(goal: goal, pinned_event: pinned) }
+        goals.size
+      end
+
+      def find_or_create_pinned_event(event)
+        PinnedEvent.find_or_create_by!(event: event) do |pe|
+          pe.display_text = truncate_event_content(event)
+        end
+      end
+
+      def truncate_event_content(event)
+        content = event.payload&.dig("content").to_s.strip
+        content = "event #{event.id}" if content.empty?
+
+        if content.length > PinnedEvent::MAX_DISPLAY_TEXT_LENGTH
+          content[0, PinnedEvent::MAX_DISPLAY_TEXT_LENGTH - 1] + "…"
+        else
+          content
+        end
+      end
+    end
+  end
+end

data/lib/mneme/tools/everything_ok.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Mneme
+  module Tools
+    # Sentinel tool signaling that Mneme has reviewed the viewport and
+    # determined no snapshot is needed. Called when the conversation
+    # context doesn't contain enough meaningful content to summarize.
+    class EverythingOk < ::Tools::Base
+      def self.tool_name = "everything_ok"
+
+      def self.description = "Signal that no snapshot is needed. " \
+        "Call this when the eviction zone contains only mechanical " \
+        "activity (tool calls) with no meaningful conversation to summarize."
+
+      def self.input_schema
+        {type: "object", properties: {}, required: []}
+      end
+
+      def execute(_input)
+        "Acknowledged. No snapshot needed."
+      end
+    end
+  end
+end

data/lib/mneme/tools/save_snapshot.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Mneme
+  module Tools
+    # Saves a summary snapshot of conversation context that is about to
+    # leave the viewport. The snapshot captures the "gist" of what happened
+    # so the agent retains awareness of past context.
+    #
+    # The text field has a max_tokens limit for predictable sizing — each
+    # snapshot is a fixed-size tile, enabling calculation of how many fit
+    # at each compression level.
+    class SaveSnapshot < ::Tools::Base
+      def self.tool_name = "save_snapshot"
+
+      def self.description = "Save a summary of the conversation context " \
+        "that is about to leave the viewport. Write a concise summary " \
+        "capturing key decisions, topics discussed, and important context. " \
+        "Focus on WHAT was decided and WHY, not mechanical details."
+
+      def self.input_schema
+        {
+          type: "object",
+          properties: {
+            text: {
+              type: "string",
+              description: "The summary text. Be concise but preserve key decisions, " \
+                "goals discussed, and important context. Max #{Anima::Settings.mneme_max_tokens} tokens."
+            }
+          },
+          required: %w[text]
+        }
+      end
+
+      # @param main_session [Session] the session being observed
+      # @param from_event_id [Integer] first event ID covered by this snapshot
+      # @param to_event_id [Integer] last event ID covered by this snapshot
+      # @param level [Integer] compression level (1 = from events, 2 = from L1 snapshots)
+      def initialize(main_session:, from_event_id:, to_event_id:, level: 1, **)
+        @main_session = main_session
+        @from_event_id = from_event_id
+        @to_event_id = to_event_id
+        @level = level
+      end
+
+      def execute(input)
+        text = input["text"].to_s.strip
+        return "Error: Summary text cannot be blank" if text.empty?
+
+        snapshot = @main_session.snapshots.create!(
+          text: text,
+          from_event_id: @from_event_id,
+          to_event_id: @to_event_id,
+          level: @level,
+          token_count: estimate_tokens(text)
+        )
+
+        "Snapshot saved (id: #{snapshot.id}, events #{@from_event_id}..#{@to_event_id})"
+      end
+
+      private
+
+      # @return [Integer] estimated token count for the summary text
+      def estimate_tokens(text)
+        [(text.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
+      end
+    end
+  end
+end

data/lib/mneme.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# Mneme — the memory department. Watches for viewport eviction and creates
+# summaries before context is lost. Named after the Greek Titaness of memory.
+#
+# Mneme is the third event bus department alongside Nous (main agent) and
+# the Analytical Brain. It operates as a phantom LLM loop: observes the
+# main session, creates snapshots, but leaves no trace of its own reasoning.
+module Mneme
+  # Dev-only logger that writes to log/mneme.log.
+  # In non-development environments returns a null logger so
+  # call sites don't need conditionals.
+  #
+  # @return [Logger]
+  def self.logger
+    @logger ||= build_logger
+  end
+
+  def self.build_logger
+    return Logger.new(File::NULL) unless Rails.env.development?
+
+    Logger.new(Rails.root.join("log", "mneme.log")).tap do |log|
+      log.formatter = proc { |severity, time, _progname, msg|
+        "[#{time.strftime("%H:%M:%S.%L")}] #{severity}  #{msg}\n"
+      }
+    end
+  end
+  private_class_method :build_logger
+end

data/lib/providers/anthropic.rb

@@ -13,6 +13,10 @@ module Providers
     API_VERSION = "2023-06-01"
     REQUIRED_BETA = "oauth-2025-04-20"
 
+    # Anthropic requires this exact string as the first system block for OAuth
+    # subscription tokens on Sonnet/Opus. Without it, /v1/messages returns 400.
+    OAUTH_PASSPHRASE = "You are Claude Code, Anthropic's official CLI for Claude."
+
     class Error < StandardError; end
     class AuthenticationError < Error; end
     class TokenFormatError < Error; end
@@ -25,11 +29,13 @@ module Providers
     class << self
       def fetch_token
         token = CredentialStore.read("anthropic", "subscription_token")
-        raise AuthenticationError, <<~MSG.strip if token.blank?
+        return token if token.present?
+        return "sk-ant-oat01-#{"0" * 68}" if ENV["CI"]
+
+        raise AuthenticationError, <<~MSG.strip
           No Anthropic subscription token found in credentials.
           Use the TUI token setup (Ctrl+a → a) to configure your token.
         MSG
-        token
       end
 
       def validate_token_format!(token)
@@ -46,6 +52,13 @@ module Providers
         true
       end
 
+      # Validate a token against the live Anthropic API.
+      # Delegates to {#validate_credentials!} on a throwaway instance.
+      #
+      # @param token [String] Anthropic API token to validate
+      # @return [true] when the API accepts the token
+      # @raise [TransientError] on network failures or server errors (retryable)
+      # @raise [AuthenticationError] on 401/403 (permanent)
       def validate_token_api!(token)
         provider = new(token)
         provider.validate_credentials!
@@ -58,7 +71,18 @@ module Providers
       @token = token || self.class.fetch_token
     end
 
+    # Send a message to the Anthropic API and return the parsed response.
+    #
+    # @param model [String] Anthropic model identifier
+    # @param messages [Array<Hash>] conversation messages
+    # @param max_tokens [Integer] maximum tokens in the response
+    # @param options [Hash] additional parameters (e.g. +system:+, +tools:+)
+    # @return [Hash] parsed API response
+    # @raise [TransientError] on network failures or server errors (retryable)
+    # @raise [AuthenticationError] on 401/403 (permanent)
+    # @raise [Error] on other API errors
     def create_message(model:, messages:, max_tokens:, **options)
+      wrap_system_prompt!(options)
       body = {model: model, messages: messages, max_tokens: max_tokens}.merge(options)
 
       response = self.class.post(
@@ -69,8 +93,8 @@ module Providers
       )
 
       handle_response(response)
-    rescue Errno::ECONNRESET, Net::ReadTimeout, Net::OpenTimeout, SocketError, EOFError => e
-      raise TransientError, "#{e.class}: #{e.message}"
+    rescue Errno::ECONNRESET, Net::ReadTimeout, Net::OpenTimeout, SocketError, EOFError => network_error
+      raise TransientError, "#{network_error.class}: #{network_error.message}"
     end
 
     # Count tokens in a message payload without creating a message.
@@ -82,6 +106,7 @@ module Providers
     # @return [Integer] estimated input token count
     # @raise [Error] on API errors
     def count_tokens(model:, messages:, **options)
+      wrap_system_prompt!(options)
       body = {model: model, messages: messages}.merge(options)
 
       response = self.class.post(
@@ -93,18 +118,22 @@ module Providers
 
       result = handle_response(response)
       result["input_tokens"]
-    rescue Errno::ECONNRESET, Net::ReadTimeout, Net::OpenTimeout, SocketError, EOFError => e
-      raise TransientError, "#{e.class}: #{e.message}"
+    rescue Errno::ECONNRESET, Net::ReadTimeout, Net::OpenTimeout, SocketError, EOFError => network_error
+      raise TransientError, "#{network_error.class}: #{network_error.message}"
     end
 
+    # Verify the token is accepted by Anthropic using the free models endpoint.
+    # Returns +true+ on success; raises typed exceptions on failure so callers
+    # can distinguish permanent auth problems from transient outages.
+    #
+    # @return [true] when the API accepts the token
+    # @raise [AuthenticationError] on 401 (invalid token) or 403 (restricted credential)
+    # @raise [RateLimitError] on 429
+    # @raise [ServerError] on 5xx
+    # @raise [TransientError] on network-level failures
     def validate_credentials!
-      response = self.class.post(
-        "/v1/messages",
-        body: {
-          model: Anima::Settings.model,
-          messages: [{role: "user", content: "Hi"}],
-          max_tokens: 1
-        }.to_json,
+      response = self.class.get(
+        "/v1/models",
         headers: request_headers,
         timeout: Anima::Settings.api_timeout
       )
@@ -121,10 +150,25 @@ module Providers
       else
         handle_response(response)
       end
+    rescue Errno::ECONNRESET, Net::ReadTimeout, Net::OpenTimeout, SocketError, EOFError => network_error
+      raise TransientError, "#{network_error.class}: #{network_error.message}"
     end
 
     private
 
+    # Wraps the system parameter in the array-of-blocks format required by
+    # Anthropic for OAuth tokens. The passphrase block is always present;
+    # the caller's prompt (if any) is appended as the second block.
+    #
+    # @param options [Hash] mutable options hash (modified in place)
+    # @return [void]
+    def wrap_system_prompt!(options)
+      prompt = options[:system]
+      blocks = [{type: "text", text: OAUTH_PASSPHRASE}]
+      blocks << {type: "text", text: prompt} if prompt
+      options[:system] = blocks
+    end
+
     def request_headers
       {
         "Authorization" => "Bearer #{token}",