anima-core 1.4.0 → 1.5.0

data/lib/anima/settings.rb

@@ -188,26 +188,12 @@ module Anima
         value
       end
 
-      # Regenerate session name every N messages.
-      # @return [Integer]
-      def name_generation_interval = get("session", "name_generation_interval")
-
       # ─── Paths ───────────────────────────────────────────────────────
 
       # Path to the soul file — the agent's self-authored identity.
       # @return [String] absolute path
       def soul_path = get("paths", "soul")
 
-      # ─── Environment ──────────────────────────────────────────────
-
-      # Filenames to scan for in the working directory.
-      # @return [Array<String>]
-      def project_files_whitelist = get("environment", "project_files")
-
-      # Maximum directory depth for project file scanning.
-      # @return [Integer]
-      def project_files_max_depth = get("environment", "project_files_max_depth")
-
       # ─── GitHub ─────────────────────────────────────────────────────
 
       # Repository for feature requests (+owner/repo+ format).
@@ -219,23 +205,15 @@ module Anima
       # @return [String]
       def github_label = get("github", "label")
 
-      # ─── Analytical Brain ─────────────────────────────────────────
+      # ─── Melete ─────────────────────────────────────────
 
-      # Maximum tokens per analytical brain response.
+      # Maximum tokens per Melete response.
       # @return [Integer]
-      def analytical_brain_max_tokens = get("analytical_brain", "max_tokens")
-
-      # Run the analytical brain synchronously before the main agent on user messages.
-      # @return [Boolean]
-      def analytical_brain_blocking_on_user_message = get("analytical_brain", "blocking_on_user_message")
-
-      # Run the analytical brain asynchronously after the main agent completes.
-      # @return [Boolean]
-      def analytical_brain_blocking_on_agent_message = get("analytical_brain", "blocking_on_agent_message")
+      def melete_max_tokens = get("melete", "max_tokens")
 
-      # Number of recent messages to include in the analytical brain's context window.
+      # Number of recent messages to include in Melete's context window.
       # @return [Integer]
-      def analytical_brain_message_window = get("analytical_brain", "message_window")
+      def melete_message_window = get("melete", "message_window")
 
       # ─── Mneme (Memory Department) ────────────────────────────────
 
@@ -243,9 +221,9 @@ module Anima
       # @return [Integer]
       def mneme_max_tokens = get("mneme", "max_tokens")
 
-      # Fraction of the main viewport token budget allocated to Mneme's viewport.
+      # Fraction of the main token budget for Mneme's eviction zone.
       # @return [Float]
-      def mneme_viewport_fraction = get("mneme", "viewport_fraction")
+      def eviction_fraction = get("mneme", "eviction_fraction")
 
       # Fraction of the main viewport token budget reserved for L1 snapshots.
       # @return [Float]
@@ -259,10 +237,6 @@ module Anima
       # @return [Integer]
       def mneme_l2_snapshot_threshold = get("mneme", "l2_snapshot_threshold")
 
-      # Fraction of the viewport to evict in batch when Mneme runs.
-      # @return [Float]
-      def mneme_eviction_fraction = get("mneme", "eviction_fraction")
-
       # Fraction of the main viewport token budget reserved for pinned messages.
       # Pinned messages appear between snapshots and the sliding window.
       # @return [Float]

data/lib/anima/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Anima
-  VERSION = "1.4.0"
+  VERSION = "1.5.0"
 end

data/lib/events/authentication_required.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted when the Anthropic provider rejects the configured token with
+  # an authentication error. Surfaces to the TUI via
+  # {Events::Subscribers::AuthenticationBroadcaster} so the user is
+  # prompted for a new token — and to the conversation as a system
+  # message so the failure is visible in history.
+  #
+  # Not persisted — not included in {Message::TYPES}.
+  class AuthenticationRequired < Base
+    TYPE = "authentication_required"
+
+    # @param session_id [Integer] session the failure is scoped to
+    # @param content [String] human-readable error text from the provider
+    def initialize(session_id:, content:)
+      super(content: content, session_id: session_id)
+    end
+
+    def type
+      TYPE
+    end
+  end
+end

data/lib/events/bounce_back.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Events
-  # Transient failure event emitted when LLM delivery fails inside the
-  # Bounce Back transaction. The user event record is rolled back, and
-  # this event notifies clients to remove the phantom message and
-  # restore the text to the input field.
+  # Transient failure event emitted by {DrainJob} when the first LLM
+  # call on a bounce-back-flagged user_message fails. The promoted
+  # Message is destroyed so the TUI can remove the phantom and restore
+  # the user's text to the input field.
   #
   # Not persisted — not included in {Message::TYPES}.
   class BounceBack < Base

data/lib/events/eviction_completed.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after Mneme advances the boundary past an eviction zone.
+  # Subscribers broadcast the cutoff to connected clients so they can
+  # drop messages below it.
+  class EvictionCompleted
+    TYPE = "eviction.completed"
+
+    attr_reader :session_id, :evict_above_id
+
+    # @param session_id [Integer] the session whose boundary advanced
+    # @param evict_above_id [Integer] last message ID in the evicted zone;
+    #   clients drop all messages with id <= this value
+    def initialize(session_id:, evict_above_id:)
+      @session_id = session_id
+      @evict_above_id = evict_above_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, evict_above_id:}
+    end
+  end
+end

data/lib/events/goal_created.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after a {Goal} record is committed for the first time.
+  # The drain pipeline's {MeleteEnrichmentJob} subscribes for the
+  # duration of one Melete run so a fresh goal triggers Mneme recall
+  # against the updated goal set before the user's message reaches the LLM.
+  class GoalCreated
+    TYPE = "goal.created"
+
+    attr_reader :session_id, :goal_id
+
+    # @param session_id [Integer] session that owns the goal
+    # @param goal_id [Integer] the newly created goal
+    def initialize(session_id:, goal_id:)
+      @session_id = session_id
+      @goal_id = goal_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, goal_id:}
+    end
+  end
+end

data/lib/events/goal_updated.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after a {Goal}'s description is changed and the change is
+  # committed. Status-only updates (finish_goal, cascade completion,
+  # mark_goal_completed) do not emit — a completed goal carries no new
+  # search seed for Mneme.
+  #
+  # The drain pipeline's {MeleteEnrichmentJob} subscribes for the
+  # duration of one Melete run so a refined goal triggers Mneme recall
+  # against the updated wording before the user's message reaches the LLM.
+  class GoalUpdated
+    TYPE = "goal.updated"
+
+    attr_reader :session_id, :goal_id
+
+    # @param session_id [Integer] session that owns the goal
+    # @param goal_id [Integer] the updated goal
+    def initialize(session_id:, goal_id:)
+      @session_id = session_id
+      @goal_id = goal_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, goal_id:}
+    end
+  end
+end

data/lib/events/llm_responded.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted by the drain loop after a single LLM round-trip completes.
+  # Carries the raw Anthropic response so downstream subscribers can
+  # persist messages, transition session state, and dispatch tool
+  # execution when the response is a +tool_use+.
+  #
+  # The drain loop hands off via this event — it does not persist
+  # Messages or release the session itself. Single responsibility:
+  # one subscriber pumps PendingMessages into the LLM, another owns
+  # the aftermath.
+  class LLMResponded
+    TYPE = "session.llm_responded"
+
+    attr_reader :session_id, :response, :api_metrics
+
+    # @param session_id [Integer] session that made the LLM call
+    # @param response [Hash] raw Anthropic response (with +content+ and +stop_reason+)
+    # @param api_metrics [Hash, nil] rate-limit and usage metrics from the provider
+    def initialize(session_id:, response:, api_metrics: nil)
+      @session_id = session_id
+      @response = response
+      @api_metrics = api_metrics
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, response:, api_metrics:}
+    end
+  end
+end

data/lib/events/message_created.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after a Message record is committed to the database.
+  # Subscribers react to persisted messages — not to raw domain events.
+  #
+  # Carries the Message record directly so subscribers don't need to
+  # look it up again.
+  class MessageCreated
+    TYPE = "message.created"
+
+    attr_reader :message
+
+    # @param message [Message] the persisted message record
+    def initialize(message)
+      @message = message
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, message:}
+    end
+  end
+end

data/lib/events/message_updated.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after a Message record is updated and committed.
+  # Used by subscribers that need to react to message changes
+  # (e.g. broadcasting updated token counts to WebSocket clients).
+  class MessageUpdated
+    TYPE = "message.updated"
+
+    attr_reader :message
+
+    # @param message [Message] the updated message record
+    def initialize(message)
+      @message = message
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, message:}
+    end
+  end
+end

data/lib/events/session_state_changed.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted when a session's transport-level state changes. Carries the
+  # AASM state after a transition (+"idle"+/+"awaiting"+/+"executing"+)
+  # or a transient UI signal (+"interrupting"+).
+  #
+  # Subscribers broadcast the state over ActionCable so the TUI spinner
+  # and sub-agent HUD update in sync.
+  class SessionStateChanged
+    TYPE = "session.state_changed"
+
+    attr_reader :session_id, :state
+
+    # @param session_id [Integer] the session the state change belongs to
+    # @param state [String] transport state name
+    def initialize(session_id:, state:)
+      @session_id = session_id
+      @state = state
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id: session_id, state: state}
+    end
+  end
+end

data/lib/events/skill_activated.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after {Session#activate_skill} enqueues a skill's phantom
+  # pair. Subscribers rebroadcast the session's active skills/workflow
+  # so the HUD reflects the new activation immediately (before the
+  # pending message even promotes).
+  class SkillActivated
+    TYPE = "skill.activated"
+
+    attr_reader :session_id, :skill_name
+
+    # @param session_id [Integer] the session the skill was activated on
+    # @param skill_name [String] canonical skill name
+    def initialize(session_id:, skill_name:)
+      @session_id = session_id
+      @skill_name = skill_name
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, skill_name:}
+    end
+  end
+end

data/lib/events/start_melete.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted when a +user_message+ PendingMessage lands on an idle session.
+  # Melete subscribes via {Events::Subscribers::MeleteKickoff} and runs
+  # its enrichment loop — activating skills, reading workflows, refining
+  # goals, renaming the session — then either:
+  #
+  # * emits {Events::StartMneme} when a goal changed during the run, so
+  #   Mneme can recall against the fresh goal set, or
+  # * emits {Events::StartProcessing} when goals were untouched, skipping
+  #   Mneme entirely (no new search seed to recall against).
+  #
+  # First stage of the +start_melete → (start_mneme) → start_processing+
+  # chain that orchestrates context enrichment before the LLM is called.
+  class StartMelete
+    TYPE = "session.start_melete"
+
+    attr_reader :session_id, :pending_message_id
+
+    # @param session_id [Integer] session whose enrichment chain should continue
+    # @param pending_message_id [Integer, nil] the PendingMessage that triggered the chain
+    def initialize(session_id:, pending_message_id: nil)
+      @session_id = session_id
+      @pending_message_id = pending_message_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, pending_message_id:}
+    end
+  end
+end

data/lib/events/start_mneme.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted by {MeleteEnrichmentJob} when goals changed during the Melete
+  # run, signalling that Mneme should recall against the fresh goal set.
+  # Mneme subscribes via {Events::Subscribers::MnemeKickoff}, performs
+  # associative recall, enqueues its memories as background PendingMessages,
+  # and emits {Events::StartProcessing} to continue the drain.
+  #
+  # Second stage of the +start_melete → (start_mneme) → start_processing+
+  # chain. Conditional — when goals are untouched the pipeline jumps
+  # straight from {Events::StartMelete} to {Events::StartProcessing}.
+  class StartMneme
+    TYPE = "session.start_mneme"
+
+    attr_reader :session_id, :pending_message_id
+
+    # @param session_id [Integer] session whose drain pipeline should start
+    # @param pending_message_id [Integer] the PendingMessage that triggered the chain
+    def initialize(session_id:, pending_message_id:)
+      @session_id = session_id
+      @pending_message_id = pending_message_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, pending_message_id:}
+    end
+  end
+end

data/lib/events/start_processing.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted when an active PendingMessage lands on an idle session and does
+  # not require the Melete/Mneme enrichment pipeline (tool calls, tool
+  # responses, sub-agent replies), or when {MeleteEnrichmentJob} finishes
+  # without a goal change, or when {MnemeEnrichmentJob} finishes recall.
+  # The drain loop subscribes and begins processing the mailbox.
+  #
+  # Final stage of the +start_melete → (start_mneme) → start_processing+
+  # chain.
+  class StartProcessing
+    TYPE = "session.start_processing"
+
+    attr_reader :session_id, :pending_message_id
+
+    # @param session_id [Integer] session whose drain loop should start
+    # @param pending_message_id [Integer, nil] the PendingMessage that triggered the chain, if any
+    def initialize(session_id:, pending_message_id: nil)
+      @session_id = session_id
+      @pending_message_id = pending_message_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, pending_message_id:}
+    end
+  end
+end

data/lib/events/subagent_evicted.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted when {Mneme::Runner} advances the boundary past every remaining
+  # trace of a sub-agent — the spawn pair plus every +from_{nickname}+
+  # phantom pair. Subscribers broadcast the removal so clients drop the
+  # entry from the HUD panel.
+  #
+  # +session_id+ is the parent session (HUD owner), +child_id+ is the
+  # sub-agent session whose traces just aged out.
+  class SubagentEvicted
+    TYPE = "subagent.evicted"
+
+    attr_reader :session_id, :child_id
+
+    # @param session_id [Integer] parent session whose HUD should drop the entry
+    # @param child_id [Integer] sub-agent session whose traces were evicted
+    def initialize(session_id:, child_id:)
+      @session_id = session_id
+      @child_id = child_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, child_id:}
+    end
+  end
+end

data/lib/events/subscribers/active_state_broadcaster.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Rebroadcasts the session's active skills and workflow whenever the
+    # set can change: skill activation, workflow activation, or Mneme
+    # eviction. Same handler, three triggers — each event carries a
+    # +session_id+ and the broadcaster reads live state off the session.
+    #
+    # @example Registering at boot
+    #   trigger = ->(event) {
+    #     %w[anima.skill.activated anima.workflow.activated anima.eviction.completed]
+    #       .include?(event[:name])
+    #   }
+    #   Events::Bus.subscribe(Events::Subscribers::ActiveStateBroadcaster.new, &trigger)
+    class ActiveStateBroadcaster
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        session_id = event.dig(:payload, :session_id)
+        session = Session.find_by(id: session_id)
+        session&.broadcast_active_state!
+      end
+    end
+  end
+end

data/lib/events/subscribers/authentication_broadcaster.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Reacts to {Events::AuthenticationRequired} by surfacing the provider
+    # rejection to the operator. Emits a +system_message+ into the
+    # conversation (so the failure lives in history) and broadcasts an
+    # +authentication_required+ frame on the session's ActionCable stream
+    # (so the TUI can prompt for a new token).
+    #
+    # Follows the same shape as {SessionStateBroadcaster}: jobs emit
+    # typed events, broadcasters own the ActionCable side.
+    class AuthenticationBroadcaster
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        session_id = payload[:session_id]
+        message = payload[:content]
+
+        Events::Bus.emit(Events::SystemMessage.new(
+          content: "Authentication failed: #{message}",
+          session_id: session_id
+        ))
+
+        ActionCable.server.broadcast(
+          "session_#{session_id}",
+          {"action" => "authentication_required", "message" => message}
+        )
+      end
+    end
+  end
+end

data/lib/events/subscribers/drain_kickoff.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Entry subscriber for the drain loop. On {Events::StartProcessing},
+    # enqueues {DrainJob} — the actual work (session claim, PM promotion,
+    # LLM call) happens in the job so the emitter's thread isn't blocked.
+    class DrainKickoff
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        session_id = event[:payload][:session_id]
+        return unless session_id
+
+        DrainJob.perform_later(session_id)
+      end
+    end
+  end
+end

data/lib/events/subscribers/eviction_broadcaster.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Events
+  module Subscribers
+    # Broadcasts eviction cutoff to connected WebSocket clients after Mneme
+    # advances the boundary. Clients drop all messages above the cutoff
+    # (id <= evict_above_id) — older messages at the top of the chat view.
+    #
+    # @example Registering at boot
+    #   Events::Bus.subscribe(Events::Subscribers::EvictionBroadcaster.new) { |event|
+    #     event[:name] == "anima.eviction.completed"
+    #   }
+    class EvictionBroadcaster
+      include Events::Subscriber
+
+      # @param event [Hash] Rails.event notification hash
+      def emit(event)
+        payload = event[:payload]
+        ActionCable.server.broadcast(
+          "session_#{payload[:session_id]}",
+          {"action" => "eviction", "evict_above_id" => payload[:evict_above_id]}
+        )
+      end
+    end
+  end
+end