anima-core 1.1.2 → 1.2.0

data/lib/analytical_brain/tools/read_workflow.rb

@@ -9,19 +9,15 @@ module AnalyticalBrain
     class ReadWorkflow < ::Tools::Base
       def self.tool_name = "read_workflow"
 
-      def self.description = "Read a workflow's full content and activate it on the session. " \
-        "Use the content to create appropriate goals with set_goal."
+      def self.description = "Activate a workflow and return its content for goal planning."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            name: {
-              type: "string",
-              description: "Name of the workflow to read (from the available workflows list)"
-            }
+            workflow_name: {type: "string"}
           },
-          required: %w[name]
+          required: %w[workflow_name]
         }
       end
 
@@ -30,11 +26,11 @@ module AnalyticalBrain
         @main_session = main_session
       end
 
-      # @param input [Hash<String, Object>] with "name" key
+      # @param input [Hash<String, Object>] with "workflow_name" key
       # @return [String] workflow name, description, and full content
       # @return [Hash] with :error key on validation failure
       def execute(input)
-        workflow_name = input["name"].to_s.strip
+        workflow_name = input["workflow_name"].to_s.strip
         return {error: "Workflow name cannot be blank"} if workflow_name.empty?
 
         workflow = @main_session.activate_workflow(workflow_name)

data/lib/analytical_brain/tools/rename_session.rb

@@ -11,21 +11,14 @@ module AnalyticalBrain
     class RenameSession < ::Tools::Base
       def self.tool_name = "rename_session"
 
-      def self.description = "Rename the conversation session. " \
-        "Use one emoji followed by 1-3 descriptive words."
+      def self.description = "Rename the session."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            emoji: {
-              type: "string",
-              description: "A single emoji representing the conversation topic"
-            },
-            name: {
-              type: "string",
-              description: "1-3 word descriptive name for the session"
-            }
+            emoji: {type: "string"},
+            name: {type: "string", description: "1-3 words."}
           },
           required: %w[emoji name]
         }

data/lib/analytical_brain/tools/set_goal.rb

@@ -8,8 +8,7 @@ module AnalyticalBrain
     class SetGoal < ::Tools::Base
       def self.tool_name = "set_goal"
 
-      def self.description = "Create a goal on the main session. " \
-        "Omit parent_goal_id for a root goal, or provide it to create a sub-goal (TODO item)."
+      def self.description = "Create a goal or sub-goal."
 
       def self.input_schema
         {
@@ -17,12 +16,9 @@ module AnalyticalBrain
           properties: {
             description: {
               type: "string",
-              description: "What needs to be accomplished (1-2 sentences)"
+              description: "1 sentence."
             },
-            parent_goal_id: {
-              type: "integer",
-              description: "ID of the parent goal (omit for root goals)"
-            }
+            parent_goal_id: {type: "integer"}
           },
           required: %w[description]
         }

data/lib/analytical_brain/tools/update_goal.rb

@@ -15,20 +15,16 @@ module AnalyticalBrain
     class UpdateGoal < ::Tools::Base
       def self.tool_name = "update_goal"
 
-      def self.description = "Update a goal's description. " \
-        "Use this to refine a goal as understanding evolves."
+      def self.description = "Refine a goal's wording as understanding evolves."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            goal_id: {
-              type: "integer",
-              description: "ID of the goal to update"
-            },
+            goal_id: {type: "integer"},
             description: {
               type: "string",
-              description: "New description for the goal (1-2 sentences)"
+              description: "1 sentence."
             }
           },
           required: %w[goal_id description]

data/lib/anima/settings.rb

@@ -60,6 +60,13 @@ module Anima
         self.config_path = nil
       end
 
+      # ─── Agent Identity ─────────────────────────────────────────────
+
+      # The agent's display name. Separates engine identity ("Anima") from
+      # agent identity — any agent running on Anima can name itself.
+      # @return [String]
+      def agent_name = get("agent", "name")
+
       # ─── LLM ───────────────────────────────────────────────────────
 
       # Primary model for conversations.
@@ -131,6 +138,10 @@ module Anima
       # @return [Integer]
       def max_web_response_bytes = get("tools", "max_web_response_bytes")
 
+      # Minimum characters of extracted web content before flagging as possibly incomplete.
+      # @return [Integer]
+      def min_web_content_chars = get("tools", "min_web_content_chars")
+
       # ─── Session ────────────────────────────────────────────────────
 
       # View mode applied to new sessions: "basic", "verbose", or "debug".
@@ -191,9 +202,9 @@ module Anima
       # @return [Boolean]
       def analytical_brain_blocking_on_agent_message = get("analytical_brain", "blocking_on_agent_message")
 
-      # Number of recent events to include in the analytical brain's context window.
+      # Number of recent messages to include in the analytical brain's context window.
       # @return [Integer]
-      def analytical_brain_event_window = get("analytical_brain", "event_window")
+      def analytical_brain_message_window = get("analytical_brain", "message_window")
 
       # ─── Mneme (Memory Department) ────────────────────────────────
 
@@ -217,8 +228,8 @@ module Anima
       # @return [Integer]
       def mneme_l2_snapshot_threshold = get("mneme", "l2_snapshot_threshold")
 
-      # Fraction of the main viewport token budget reserved for pinned events.
-      # Pinned events appear between snapshots and the sliding window.
+      # Fraction of the main viewport token budget reserved for pinned messages.
+      # Pinned messages appear between snapshots and the sliding window.
       # @return [Float]
       def mneme_pinned_budget_fraction = get("mneme", "pinned_budget_fraction")
 
@@ -236,6 +247,10 @@ module Anima
       # @return [Integer]
       def recall_max_snippet_tokens = get("recall", "max_snippet_tokens")
 
+      # Recency decay factor for search ranking (0.0 = pure relevance).
+      # @return [Float]
+      def recall_recency_decay = get("recall", "recency_decay")
+
       private
 
       # Reads a setting from the config file.

data/lib/anima/version.rb

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

data/lib/events/bounce_back.rb

@@ -6,24 +6,24 @@ module Events
   # this event notifies clients to remove the phantom message and
   # restore the text to the input field.
   #
-  # Not persisted — not included in {Event::TYPES}.
+  # Not persisted — not included in {Message::TYPES}.
   class BounceBack < Base
     TYPE = "bounce_back"
 
     # @return [String] human-readable error description
     attr_reader :error
 
-    # @return [Integer, nil] database ID of the rolled-back event (for client-side removal)
-    attr_reader :event_id
+    # @return [Integer, nil] database ID of the rolled-back message (for client-side removal)
+    attr_reader :message_id
 
     # @param content [String] original user message text to restore to input
     # @param error [String] error description for the flash message
     # @param session_id [Integer] session the message was intended for
-    # @param event_id [Integer, nil] ID of the event that was broadcast optimistically
-    def initialize(content:, error:, session_id:, event_id: nil)
+    # @param message_id [Integer, nil] ID of the message that was broadcast optimistically
+    def initialize(content:, error:, session_id:, message_id: nil)
       super(content: content, session_id: session_id)
       @error = error
-      @event_id = event_id
+      @message_id = message_id
     end
 
     def type
@@ -31,7 +31,7 @@ module Events
     end
 
     def to_h
-      super.merge(error: error, event_id: event_id)
+      super.merge(error: error, message_id: message_id)
     end
   end
 end

data/lib/events/subscribers/persister.rb

@@ -3,7 +3,7 @@
 module Events
   module Subscribers
     # Persists all events to SQLite as they flow through the event bus.
-    # Each event is written as an Event record belonging to the active session.
+    # Each event is written as a Message record belonging to the active session.
     #
     # When initialized with a specific session, all events are saved to that
     # session. When initialized without one (global mode), the session is
@@ -31,7 +31,7 @@ module Events
       # Skips non-pending user messages — those are persisted by their
       # callers ({SessionChannel#speak} for idle sessions,
       # {AgentLoop#process} for direct usage). Also skips event types
-      # not in {Event::TYPES} (transient events like {Events::BounceBack}).
+      # not in {Message::TYPES} (transient events like {Events::BounceBack}).
       #
       # @param event [Hash] with :payload containing event data
       def emit(event)
@@ -40,15 +40,15 @@ module Events
 
         event_type = payload[:type]
         return if event_type.nil?
-        return unless Event::TYPES.include?(event_type)
+        return unless Message::TYPES.include?(event_type)
         return if persisted_by_job?(event_type, payload)
 
         target_session = @session || Session.find_by(id: payload[:session_id])
         return unless target_session
 
         @mutex.synchronize do
-          target_session.events.create!(
-            event_type: event_type,
+          target_session.messages.create!(
+            message_type: event_type,
             payload: payload,
             status: payload[:status],
             tool_use_id: payload[:tool_use_id],
@@ -64,12 +64,12 @@ module Events
       private
 
       # Non-pending user messages are persisted by their callers
-      # ({SessionChannel#speak}, {AgentLoop#process}) so the event ID
+      # ({SessionChannel#speak}, {AgentLoop#process}) so the message ID
       # is available for bounce-back cleanup if LLM delivery fails.
       # Pending messages are still auto-persisted here because they
       # queue while the session is busy.
       def persisted_by_job?(event_type, payload)
-        event_type == "user_message" && payload[:status] != Event::PENDING_STATUS
+        event_type == "user_message" && payload[:status] != Message::PENDING_STATUS
       end
     end
   end

data/lib/events/subscribers/subagent_message_router.rb

@@ -6,16 +6,19 @@ module Events
     # bidirectional @mention communication.
     #
     # **Child → Parent:** When a sub-agent emits an {Events::AgentMessage},
-    # the router persists a {Events::UserMessage} in the parent session
-    # with attribution prefix, then wakes the parent via {AgentRequestJob}.
+    # the router creates a {Events::UserMessage} in the parent session
+    # with attribution prefix. If the parent is idle, persists directly
+    # and wakes it via {AgentRequestJob}. If the parent is mid-turn,
+    # emits a pending message that is promoted after the current loop
+    # completes — same mechanism as {SessionChannel#speak}.
     #
     # **Parent → Child:** When a parent agent emits an {Events::AgentMessage}
     # containing `@name` mentions, the router persists the message in each
     # matching child session and wakes them via {AgentRequestJob}.
     #
-    # Both directions use direct persistence + job enqueue (same pattern as
-    # {Tools::SpawnSubagent#spawn_child}) to avoid conflicts with the global
-    # {Persister} which skips non-pending user messages.
+    # Both directions delegate to {Session#enqueue_user_message}, which
+    # respects the target session's processing state — persisting directly
+    # when idle, deferring via pending queue when mid-turn.
     #
     # This replaces the +return_result+ tool — sub-agents communicate
     # through natural text messages instead of structured tool calls.
@@ -60,9 +63,8 @@ module Events
 
       private
 
-      # Forwards a sub-agent's text message to its parent session.
-      # Persists directly and enqueues a job so the parent agent wakes
-      # up to process the message.
+      # Forwards a sub-agent's text message to its parent session
+      # via {Session#enqueue_user_message}.
       #
       # @param child [Session] the sub-agent session
       # @param content [String] the sub-agent's message text
@@ -73,8 +75,7 @@ module Events
         name = child.name || "agent-#{child.id}"
         attributed = format(ATTRIBUTION_FORMAT, name, content)
 
-        parent.create_user_event(attributed)
-        AgentRequestJob.perform_later(parent.id)
+        parent.enqueue_user_message(attributed)
       end
 
       # Scans a parent agent's message for @mentions and routes the message
@@ -93,8 +94,7 @@ module Events
           child = active_children[name]
           next unless child
 
-          child.create_user_event(content)
-          AgentRequestJob.perform_later(child.id)
+          child.enqueue_user_message(content)
         end
       end
     end

data/lib/events/subscribers/transient_broadcaster.rb

@@ -3,8 +3,8 @@
 module Events
   module Subscribers
     # Bridges transient (non-persisted) events to ActionCable so clients
-    # receive them over WebSocket. Persisted events reach clients via
-    # {Event::Broadcasting} callbacks; this subscriber handles events
+    # receive them over WebSocket. Persisted messages reach clients via
+    # {Message::Broadcasting} callbacks; this subscriber handles events
     # that never touch the database.
     #
     # @example Registering at boot

data/lib/llm/client.rb

@@ -177,9 +177,12 @@ module LLM
     # tool raises. Per the Anthropic tool-use protocol, every tool_use must
     # have a matching tool_result; a missing result permanently corrupts the
     # conversation history and breaks the session.
+    #
+    # Falls back to SecureRandom.uuid when Anthropic omits the tool_use id,
+    # ensuring the ToolCall/ToolResponse pair always shares a valid identifier.
     def execute_single_tool(tool_use, registry, session_id)
       name = tool_use["name"]
-      id = tool_use["id"]
+      id = tool_use["id"] || SecureRandom.uuid
       input = tool_use["input"] || {}
       timeout = input["timeout"] || Anima::Settings.tool_timeout
 
@@ -231,7 +234,7 @@ module LLM
     # @return [Hash] tool_result content block
     def interrupt_tool(tool_use, session_id)
       name = tool_use["name"]
-      id = tool_use["id"]
+      id = tool_use["id"] || SecureRandom.uuid
       input = tool_use["input"] || {}
 
       Events::Bus.emit(Events::ToolCall.new(

data/lib/mneme/compressed_viewport.rb

@@ -7,16 +7,16 @@ module Mneme
   # aggregate counters like `[4 tools called]`.
   #
   # The viewport is split into three zones separated by delimiters:
-  # - **Eviction zone** — events about to leave the viewport (upper third)
-  # - **Middle zone** — events in the middle of the viewport
-  # - **Recent zone** — the most recent events (lower third)
+  # - **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 ──\nevent 42 User: ..."
+  #   viewport.render  #=> "── EVICTION ZONE ──\nmessage 42 User: ..."
   class CompressedViewport
     ZONE_DELIMITERS = {
       eviction: "── EVICTION ZONE (upper third) ──",
@@ -26,74 +26,74 @@ module Mneme
 
     # @param session [Session] the session to build viewport for
     # @param token_budget [Integer] total tokens available for Mneme's viewport
-    # @param from_event_id [Integer, nil] start from this event ID (inclusive);
+    # @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_event_id: nil)
+    def initialize(session, token_budget:, from_message_id: nil)
       @session = session
       @token_budget = token_budget
-      @from_event_id = from_event_id
+      @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 events.empty?
+      return "" if messages.empty?
 
-      zones = split_into_zones(events)
+      zones = split_into_zones(messages)
       render_zones(zones)
     end
 
-    # @return [Array<Event>] the raw events selected for this viewport
-    def events
-      @events ||= fetch_events
+    # @return [Array<Message>] the raw messages selected for this viewport
+    def messages
+      @messages ||= fetch_messages
     end
 
     private
 
-    # Fetches events within token budget, starting from from_event_id.
+    # Fetches messages within token budget, starting from from_message_id.
     # Selects newest-first until budget exhausted, returns chronological.
-    # Caches per-event token costs in @event_costs for reuse by split_into_zones.
+    # Caches per-message token costs in @message_costs for reuse by split_into_zones.
     #
-    # @return [Array<Event>]
-    def fetch_events
-      scope = @session.events.context_events.deliverable
+    # @return [Array<Message>]
+    def fetch_messages
+      scope = @session.messages.context_messages.deliverable
 
-      if @from_event_id
-        scope = scope.where("id >= ?", @from_event_id)
+      if @from_message_id
+        scope = scope.where("id >= ?", @from_message_id)
       end
 
       selected = []
-      @event_costs = {}
+      @message_costs = {}
       remaining = @token_budget
 
-      scope.reorder(id: :desc).each do |event|
-        cost = event_token_cost(event)
+      scope.reorder(id: :desc).each do |message|
+        cost = message_token_cost(message)
         break if cost > remaining && selected.any?
 
-        selected << event
-        @event_costs[event.id] = cost
+        selected << message
+        @message_costs[message.id] = cost
         remaining -= cost
       end
 
       selected.reverse
     end
 
-    # Splits events into three zones by token count.
-    # Zone boundaries are calculated including ALL events (tool calls count
+    # 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<Event>}] :eviction, :middle, :recent
-    def split_into_zones(events)
-      costs = events.map { |event| [event, @event_costs[event.id] || event_token_cost(event)] }
+    # @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 |event, cost|
+      costs.each do |message, cost|
         cumulative += cost
-        result[zone_for_cumulative(cumulative, zone_size)] << event
+        result[zone_for_cumulative(cumulative, zone_size)] << message
       end
 
       result
@@ -101,7 +101,7 @@ module Mneme
 
     # Renders zones with delimiters, compressing tool calls into counters.
     #
-    # @param zones [Hash{Symbol => Array<Event>}]
+    # @param zones [Hash{Symbol => Array<Message>}]
     # @return [String]
     def render_zones(zones)
       %i[eviction middle recent].flat_map { |name|
@@ -124,23 +124,23 @@ module Mneme
       end
     end
 
-    # Renders a single zone: conversation events as full text, consecutive
+    # Renders a single zone: conversation messages as full text, consecutive
     # tool calls/responses compressed into `[N tools called]` counters.
-    # tool_response events are intentionally silent — they affect zone boundaries
-    # via token cost but are not rendered; only tool_call events increment the counter.
+    # 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_events [Array<Event>]
+    # @param zone_messages [Array<Message>]
     # @return [String]
-    def render_zone(zone_events)
+    def render_zone(zone_messages)
       lines = []
       tool_count = 0
 
-      zone_events.each do |event|
-        if conversation_event?(event) || think_event?(event)
+      zone_messages.each do |message|
+        if conversation_message?(message) || think_message?(message)
           lines << flush_tool_count(tool_count)
           tool_count = 0
-          lines << render_event_line(event)
-        elsif event.event_type == "tool_call"
+          lines << render_message_line(message)
+        elsif message.message_type == "tool_call"
           tool_count += 1
         end
       end
@@ -149,17 +149,17 @@ module Mneme
       lines.compact.join("\n")
     end
 
-    # @return [Boolean] true if event is a user/agent/system message
-    def conversation_event?(event)
-      event.event_type.in?(Event::CONVERSATION_TYPES)
+    # @return [Boolean] true if message is a user/agent/system message
+    def conversation_message?(message)
+      message.message_type.in?(Message::CONVERSATION_TYPES)
     end
 
-    # Think events are tool_call events with tool_name == "think".
+    # 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_event?(event)
-      event.event_type == "tool_call" && event.payload["tool_name"] == Event::THINK_TOOL
+    def think_message?(message)
+      message.message_type == "tool_call" && message.payload["tool_name"] == Message::THINK_TOOL
     end
 
     ROLE_LABELS = {
@@ -168,17 +168,17 @@ module Mneme
       "system_message" => "System"
     }.freeze
 
-    # Renders a single event as a transcript line.
+    # Renders a single message as a transcript line.
     #
-    # @param event [Event]
+    # @param message [Message]
     # @return [String]
-    def render_event_line(event)
-      prefix = "event #{event.id}"
-      data = event.payload
-      if think_event?(event)
+    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(event.event_type)}: #{data["content"]}"
+        "#{prefix} #{ROLE_LABELS.fetch(message.message_type)}: #{data["content"]}"
       end
     end
 
@@ -192,9 +192,9 @@ module Mneme
     end
 
     # @return [Integer] token cost using cached count or heuristic
-    def event_token_cost(event)
-      cached = event.token_count
-      (cached > 0) ? cached : event.estimate_tokens
+    def message_token_cost(message)
+      cached = message.token_count
+      (cached > 0) ? cached : message.estimate_tokens
     end
   end
 end

data/lib/mneme/l2_runner.rb

@@ -110,22 +110,22 @@ module Mneme
     # @return [Array<Hash>] single-element messages array
     def build_messages(snapshots)
       content = snapshots.map.with_index(1) { |snap, idx|
-        "--- Snapshot #{idx} (events #{snap.from_event_id}..#{snap.to_event_id}) ---\n#{snap.text}"
+        "--- Snapshot #{idx} (messages #{snap.from_message_id}..#{snap.to_message_id}) ---\n#{snap.text}"
       }.join("\n\n")
 
       [{role: "user", content: "Compress these #{snapshots.size} Level 1 snapshots into a single Level 2 summary:\n\n#{content}"}]
     end
 
     # Builds the tool registry with L2 context for SaveSnapshot.
-    # The event range spans from the first L1's start to the last L1's end.
+    # The message range spans from the first L1's start to the last L1's end.
     #
     # @param snapshots [Array<Snapshot>]
     # @return [Tools::Registry]
     def build_registry(snapshots)
       registry = ::Tools::Registry.new(context: {
         main_session: @session,
-        from_event_id: snapshots.first.from_event_id,
-        to_event_id: snapshots.last.to_event_id,
+        from_message_id: snapshots.first.from_message_id,
+        to_message_id: snapshots.last.to_message_id,
         level: 2
       })
       TOOLS.each { |tool| registry.register(tool) }

data/lib/mneme/passive_recall.rb

@@ -32,8 +32,8 @@ module Mneme
 
       # Exclude events from the current session's viewport — no point recalling
       # what the agent already sees.
-      viewport_ids = @session.viewport_event_ids.to_set
-      results.reject { |result| viewport_ids.include?(result.event_id) }
+      viewport_ids = @session.viewport_message_ids.to_set
+      results.reject { |result| viewport_ids.include?(result.message_id) }
     end
 
     private