anima-core 1.1.3 → 1.2.0

data/app/jobs/agent_request_job.rb

@@ -5,18 +5,18 @@
 #
 # Supports two modes:
 #
-# **Immediate Persist (event_id provided):** The user event was already
+# **Immediate Persist (message_id provided):** The user message was already
 # persisted and broadcast by the caller (e.g. {SessionChannel#speak}).
 # The job verifies LLM delivery — if the first API call fails, the
-# event is deleted and a {Events::BounceBack} is emitted so clients
+# message is deleted and a {Events::BounceBack} is emitted so clients
 # can restore the text to the input field.
 #
-# **Standard (no event_id):** Processes already-persisted events (e.g.
+# **Standard (no message_id):** Processes already-persisted messages (e.g.
 # after pending message promotion). Uses ActiveJob retry/discard for
 # error handling.
 #
-# @example Immediate Persist — event already saved by SessionChannel
-#   AgentRequestJob.perform_later(session.id, event_id: 42)
+# @example Immediate Persist — message already saved by SessionChannel
+#   AgentRequestJob.perform_later(session.id, message_id: 42)
 #
 # @example Standard — pending message processing
 #   AgentRequestJob.perform_later(session.id)
@@ -49,8 +49,8 @@ class AgentRequestJob < ApplicationJob
   end
 
   # @param session_id [Integer] ID of the session to process
-  # @param event_id [Integer, nil] ID of a pre-persisted user event (triggers delivery verification)
-  def perform(session_id, event_id: nil)
+  # @param message_id [Integer, nil] ID of a pre-persisted user message (triggers delivery verification)
+  def perform(session_id, message_id: nil)
     session = Session.find(session_id)
 
     # Atomic: only one job processes a session at a time.
@@ -60,8 +60,8 @@ class AgentRequestJob < ApplicationJob
 
     agent_loop = AgentLoop.new(session: session)
 
-    if event_id
-      deliver_persisted_event(session, event_id, agent_loop)
+    if message_id
+      deliver_persisted_message(session, message_id, agent_loop)
     else
       agent_loop.run
     end
@@ -82,11 +82,11 @@ class AgentRequestJob < ApplicationJob
 
   private
 
-  # Verifies LLM delivery for a pre-persisted user event.
+  # Verifies LLM delivery for a pre-persisted user message.
   #
-  # The event was already created and broadcast by the caller, so
+  # The message was already created and broadcast by the caller, so
   # the user sees their message immediately. This method makes the
-  # first LLM API call — if it fails, the event is deleted and a
+  # first LLM API call — if it fails, the message is deleted and a
   # {Events::BounceBack} notifies clients to remove the phantom
   # message and restore the text to the input field. For
   # {Providers::Anthropic::AuthenticationError}, an additional
@@ -102,26 +102,26 @@ class AgentRequestJob < ApplicationJob
   # execution, subsequent API calls).
   #
   # @param session [Session] the conversation session
-  # @param event_id [Integer] database ID of the pre-persisted user event
+  # @param message_id [Integer] database ID of the pre-persisted user message
   # @param agent_loop [AgentLoop] agent loop instance (reused for continuation)
-  def deliver_persisted_event(session, event_id, agent_loop)
-    event = Event.find_by(id: event_id, session_id: session.id)
-    # Event may have been deleted between SessionChannel#speak and job
+  def deliver_persisted_message(session, message_id, agent_loop)
+    message = Message.find_by(id: message_id, session_id: session.id)
+    # Message may have been deleted between SessionChannel#speak and job
     # execution (e.g. user recalled the message). Exit silently — there
     # is nothing to deliver or bounce back.
-    return unless event
+    return unless message
 
-    content = event.payload["content"]
+    content = message.payload["content"]
 
     begin
       agent_loop.deliver!
     rescue => error
-      event.destroy!
+      message.destroy!
       Events::Bus.emit(Events::BounceBack.new(
         content: content,
         error: error.message,
         session_id: session.id,
-        event_id: event_id
+        message_id: message_id
       ))
       broadcast_auth_required(session.id, error) if error.is_a?(Providers::Anthropic::AuthenticationError)
       return

data/app/jobs/count_message_tokens_job.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# Counts tokens in a message's payload via the Anthropic API and
+# caches the result on the message record. Enqueued automatically
+# after each LLM message is created.
+class CountMessageTokensJob < ApplicationJob
+  queue_as :default
+
+  retry_on Providers::Anthropic::Error, wait: :polynomially_longer, attempts: 3
+  discard_on ActiveRecord::RecordNotFound
+
+  # @param message_id [Integer] the Message record to count tokens for
+  def perform(message_id)
+    message = Message.find(message_id)
+    return if already_counted?(message)
+
+    provider = Providers::Anthropic.new
+    api_messages = [{role: message.api_role, content: message.payload["content"].to_s}]
+
+    token_count = provider.count_tokens(
+      model: Anima::Settings.model,
+      messages: api_messages
+    )
+
+    # Guard against parallel jobs: reload and re-check before writing.
+    # Uses update! (not update_all) so {Message::Broadcasting} after_update_commit
+    # broadcasts the updated token count to connected clients.
+    message.reload
+    return if already_counted?(message)
+
+    message.update!(token_count: token_count)
+  end
+
+  private
+
+  def already_counted?(message)
+    message.token_count > 0
+  end
+end

data/app/jobs/passive_recall_job.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# Runs passive recall after goal updates — searches event history for
+# Runs passive recall after goal updates — searches message history for
 # context relevant to active goals and caches results on the session
 # for viewport injection.
 #
@@ -20,10 +20,10 @@ class PassiveRecallJob < ApplicationJob
     results = Mneme::PassiveRecall.new(session).call
 
     if results.any?
-      session.update_column(:recalled_event_ids, results.map(&:event_id))
+      session.update_column(:recalled_message_ids, results.map(&:message_id))
       Mneme.logger.info("session=#{session_id} — passive recall found #{results.size} memories")
-    elsif session.recalled_event_ids.present?
-      session.update_column(:recalled_event_ids, [])
+    elsif session.recalled_message_ids.present?
+      session.update_column(:recalled_message_ids, [])
     end
   end
 end

data/app/models/concerns/{event → message}/broadcasting.rb

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
-# Broadcasts Event records to connected WebSocket clients via ActionCable.
-# Follows the Turbo Streams pattern: events are broadcast on both create
+# Broadcasts Message records to connected WebSocket clients via ActionCable.
+# Follows the Turbo Streams pattern: messages are broadcast on both create
 # and update, with an action type so clients can distinguish append from
 # replace operations.
 #
-# Each broadcast includes the Event's database ID, enabling clients to
+# Each broadcast includes the Message's database ID, enabling clients to
 # maintain an ID-indexed store for efficient in-place updates (e.g. when
-# token counts arrive asynchronously from {CountEventTokensJob}).
+# token counts arrive asynchronously from {CountMessageTokensJob}).
 #
-# When a new event pushes old events out of the LLM's context window,
-# the broadcast includes `evicted_event_ids` so clients can remove
+# When a new message pushes old messages out of the LLM's context window,
+# the broadcast includes `evicted_message_ids` so clients can remove
 # phantom messages that the agent no longer knows about.
 #
 # @example Create broadcast payload
@@ -24,7 +24,7 @@
 #   {
 #     "type" => "agent_message", "content" => "...", ...,
 #     "id" => 99, "action" => "create",
-#     "evicted_event_ids" => [101, 102, 103]
+#     "evicted_message_ids" => [101, 102, 103]
 #   }
 #
 # @example Update broadcast payload (e.g. token count arrives)
@@ -33,7 +33,7 @@
 #     "id" => 42, "action" => "update",
 #     "rendered" => { "debug" => { "role" => "user", "content" => "hello", "tokens" => 15 } }
 #   }
-module Event::Broadcasting
+module Message::Broadcasting
   extend ActiveSupport::Concern
 
   ACTION_CREATE = "create"
@@ -47,26 +47,26 @@ module Event::Broadcasting
   private
 
   def broadcast_create
-    broadcast_event(action: ACTION_CREATE)
+    broadcast_message(action: ACTION_CREATE)
   end
 
   def broadcast_update
-    broadcast_event(action: ACTION_UPDATE)
+    broadcast_message(action: ACTION_UPDATE)
   end
 
-  # Decorates the event for the session's current view mode and broadcasts
+  # Decorates the message for the session's current view mode and broadcasts
   # the payload to the session's ActionCable stream. Includes viewport
   # eviction metadata so clients can remove messages the LLM has forgotten.
   #
-  # @param action [String] ACTION_CREATE or ACTION_UPDATE — tells clients how to handle the event
-  def broadcast_event(action:)
+  # @param action [String] ACTION_CREATE or ACTION_UPDATE — tells clients how to handle the message
+  def broadcast_message(action:)
     return unless session_id
 
     session = Session.find_by(id: session_id)
     return unless session
 
     mode = session.view_mode
-    decorator = EventDecorator.for(self)
+    decorator = MessageDecorator.for(self)
     broadcast_payload = payload.merge("id" => id, "action" => action)
 
     if decorator
@@ -74,11 +74,11 @@ module Event::Broadcasting
     end
 
     evicted_ids = session.recalculate_viewport!
-    broadcast_payload["evicted_event_ids"] = evicted_ids if evicted_ids.any?
+    broadcast_payload["evicted_message_ids"] = evicted_ids if evicted_ids.any?
 
     # The nil? branch fires on every broadcast until boundary initializes, but
     # schedule_mneme! returns early after setting the boundary — cost is one DB read + write.
-    session.schedule_mneme! if evicted_ids.any? || session.mneme_boundary_event_id.nil?
+    session.schedule_mneme! if evicted_ids.any? || session.mneme_boundary_message_id.nil?
 
     ActionCable.server.broadcast("session_#{session_id}", broadcast_payload)
   end

data/app/models/goal.rb

@@ -13,8 +13,8 @@ class Goal < ApplicationRecord
   belongs_to :session
   belongs_to :parent_goal, class_name: "Goal", optional: true
   has_many :sub_goals, -> { order(:created_at) }, class_name: "Goal", foreign_key: :parent_goal_id, dependent: :destroy
-  has_many :goal_pinned_events, dependent: :destroy
-  has_many :pinned_events, through: :goal_pinned_events
+  has_many :goal_pinned_messages, dependent: :destroy
+  has_many :pinned_messages, through: :goal_pinned_messages
 
   validates :description, presence: true
   validates :status, inclusion: {in: STATUSES}
@@ -52,14 +52,14 @@ class Goal < ApplicationRecord
     sub_goals.active.update_all(status: "completed", completed_at: now, updated_at: now)
   end
 
-  # Releases pinned events that have no remaining active Goal references
+  # Releases pinned messages that have no remaining active Goal references
   # anywhere in the session. Called after goal (and cascade) completion —
   # the orphaned scope checks all Goals, so pins shared with other active
   # Goals survive automatically via reference counting.
   #
   # @return [Integer] number of released pins
   def release_orphaned_pins!
-    orphaned = session.pinned_events.orphaned
+    orphaned = session.pinned_messages.orphaned
     orphaned.destroy_all.size
   end
 

data/app/models/goal_pinned_message.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Join record linking a {Goal} to a {PinnedMessage}. Many-to-many: one message
+# can be pinned to multiple Goals, and one Goal can reference multiple pins.
+# When the last Goal referencing a pin completes, the pin is released.
+class GoalPinnedMessage < ApplicationRecord
+  belongs_to :goal
+  belongs_to :pinned_message
+
+  validates :pinned_message_id, uniqueness: {scope: :goal_id}
+end

data/app/models/{event.rb → message.rb}

@@ -1,24 +1,27 @@
 # frozen_string_literal: true
 
-# A persisted record of something that happened during a session.
-# Events are the single source of truth for conversation history —
-# there is no separate chat log, only events attached to a session.
+# A persisted record of what was said during a session — by whom and when.
+# Messages are the single source of truth for conversation history —
+# there is no separate chat log, only messages attached to a session.
 #
-# @!attribute event_type
+# Not to be confused with {Events::Base} (transient bus signals).
+# Messages persist to SQLite; events flow through the bus and are gone.
+#
+# @!attribute message_type
 #   @return [String] one of {TYPES}: system_message, user_message,
 #     agent_message, tool_call, tool_response
 # @!attribute payload
-#   @return [Hash] event-specific data (content, tool_name, tool_input, etc.)
+#   @return [Hash] message-specific data (content, tool_name, tool_input, etc.)
 # @!attribute timestamp
 #   @return [Integer] nanoseconds since epoch (Process::CLOCK_REALTIME)
 # @!attribute token_count
-#   @return [Integer] cached token count for this event's payload (0 until counted)
+#   @return [Integer] cached token count for this message's payload (0 until counted)
 # @!attribute tool_use_id
-#   @return [String] ID correlating tool_call and tool_response events
+#   @return [String] ID correlating tool_call and tool_response messages
 #     (Anthropic-assigned, or a SecureRandom.uuid fallback when the API returns nil;
-#     required for tool_call and tool_response events)
-class Event < ApplicationRecord
-  include Event::Broadcasting
+#     required for tool_call and tool_response messages)
+class Message < ApplicationRecord
+  include Message::Broadcasting
 
   TYPES = %w[system_message user_message agent_message tool_call tool_response].freeze
   LLM_TYPES = %w[user_message agent_message].freeze
@@ -28,7 +31,7 @@ class Event < ApplicationRecord
   SPAWN_TOOLS = %w[spawn_subagent spawn_specialist].freeze
   PENDING_STATUS = "pending"
 
-  # Event types that require a tool_use_id to pair call with response.
+  # Message types that require a tool_use_id to pair call with response.
   TOOL_TYPES = %w[tool_call tool_response].freeze
 
   ROLE_MAP = {"user_message" => "user", "agent_message" => "assistant"}.freeze
@@ -37,25 +40,25 @@ class Event < ApplicationRecord
   BYTES_PER_TOKEN = 4
 
   belongs_to :session
-  has_many :pinned_events, dependent: :destroy
+  has_many :pinned_messages, dependent: :destroy
 
-  validates :event_type, presence: true, inclusion: {in: TYPES}
+  validates :message_type, presence: true, inclusion: {in: TYPES}
   validates :payload, presence: true
   validates :timestamp, presence: true
   # Anthropic requires every tool_use to have a matching tool_result with the same ID
-  validates :tool_use_id, presence: true, if: -> { event_type.in?(TOOL_TYPES) }
+  validates :tool_use_id, presence: true, if: -> { message_type.in?(TOOL_TYPES) }
 
   after_create :schedule_token_count, if: :llm_message?
 
   # @!method self.llm_messages
-  #   Events that represent conversation turns sent to the LLM API.
+  #   Messages that represent conversation turns sent to the LLM API.
   #   @return [ActiveRecord::Relation]
-  scope :llm_messages, -> { where(event_type: LLM_TYPES) }
+  scope :llm_messages, -> { where(message_type: LLM_TYPES) }
 
-  # @!method self.context_events
-  #   Events included in the LLM context window (messages + tool interactions).
+  # @!method self.context_messages
+  #   Messages included in the LLM context window (conversation + tool interactions).
   #   @return [ActiveRecord::Relation]
-  scope :context_events, -> { where(event_type: CONTEXT_TYPES) }
+  scope :context_messages, -> { where(message_type: CONTEXT_TYPES) }
 
   # @!method self.pending
   #   User messages queued during active agent processing, not yet sent to LLM.
@@ -63,36 +66,36 @@ class Event < ApplicationRecord
   scope :pending, -> { where(status: PENDING_STATUS) }
 
   # @!method self.deliverable
-  #   Events eligible for LLM context (excludes pending messages).
+  #   Messages eligible for LLM context (excludes pending messages).
   #   NULL status means delivered/processed — the only excluded value is "pending".
   #   @return [ActiveRecord::Relation]
   scope :deliverable, -> { where(status: nil) }
 
-  # @!method self.excluding_spawn_events
-  #   Excludes spawn_subagent/spawn_specialist tool_call and tool_response events.
-  #   Used when building parent context for sub-agents — spawn events cause role
+  # @!method self.excluding_spawn_messages
+  #   Excludes spawn_subagent/spawn_specialist tool_call and tool_response messages.
+  #   Used when building parent context for sub-agents — spawn messages cause role
   #   confusion because the sub-agent sees sibling spawn results and mistakes
   #   itself for the parent.
   #   @return [ActiveRecord::Relation]
-  scope :excluding_spawn_events, -> {
-    where.not("event_type IN (?) AND json_extract(payload, '$.tool_name') IN (?)",
+  scope :excluding_spawn_messages, -> {
+    where.not("message_type IN (?) AND json_extract(payload, '$.tool_name') IN (?)",
       TOOL_TYPES, SPAWN_TOOLS)
   }
 
-  # Maps event_type to the Anthropic Messages API role.
+  # Maps message_type to the Anthropic Messages API role.
   # @return [String] "user" or "assistant"
   def api_role
-    ROLE_MAP.fetch(event_type)
+    ROLE_MAP.fetch(message_type)
   end
 
-  # @return [Boolean] true if this event represents an LLM conversation turn
+  # @return [Boolean] true if this message represents an LLM conversation turn
   def llm_message?
-    event_type.in?(LLM_TYPES)
+    message_type.in?(LLM_TYPES)
   end
 
-  # @return [Boolean] true if this event is part of the LLM context window
-  def context_event?
-    event_type.in?(CONTEXT_TYPES)
+  # @return [Boolean] true if this message is part of the LLM context window
+  def context_message?
+    message_type.in?(CONTEXT_TYPES)
   end
 
   # @return [Boolean] true if this is a pending message not yet sent to the LLM
@@ -100,20 +103,20 @@ class Event < ApplicationRecord
     status == PENDING_STATUS
   end
 
-  # @return [Boolean] true if this is a conversation event (user/agent/system message)
-  #   or a think tool_call — the events Mneme treats as "conversation" for boundary tracking
+  # @return [Boolean] true if this is a conversation message (user/agent/system)
+  #   or a think tool_call — the messages Mneme treats as "conversation" for boundary tracking
   def conversation_or_think?
-    event_type.in?(CONVERSATION_TYPES) ||
-      (event_type == "tool_call" && payload["tool_name"] == THINK_TOOL)
+    message_type.in?(CONVERSATION_TYPES) ||
+      (message_type == "tool_call" && payload["tool_name"] == THINK_TOOL)
   end
 
   # Heuristic token estimate: ~4 bytes per token for English prose.
-  # Tool events are estimated from the full payload JSON since tool_input
+  # Tool messages are estimated from the full payload JSON since tool_input
   # and tool metadata contribute to token count. Messages use content only.
   #
   # @return [Integer] estimated token count (at least 1)
   def estimate_tokens
-    text = if event_type.in?(TOOL_TYPES)
+    text = if message_type.in?(TOOL_TYPES)
       payload.to_json
     else
       payload["content"].to_s
@@ -124,6 +127,6 @@ class Event < ApplicationRecord
   private
 
   def schedule_token_count
-    CountEventTokensJob.perform_later(id)
+    CountMessageTokensJob.perform_later(id)
   end
 end

data/app/models/pinned_message.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+# A conversation message pinned to one or more Goals by Mneme to protect it
+# from viewport eviction. Pinned messages appear in the Goals section of
+# the viewport, giving the main agent access to critical context that
+# would otherwise scroll out of the sliding window.
+#
+# Pinning is goal-scoped: when all Goals referencing a pin complete,
+# the pin is automatically released (reference-counted cleanup).
+#
+# @!attribute display_text
+#   @return [String] truncated message content (~200 chars) shown in the Goals section
+class PinnedMessage < ApplicationRecord
+  # Display text limit — enough to recognize content, cheap on tokens.
+  MAX_DISPLAY_TEXT_LENGTH = 200
+
+  belongs_to :message
+
+  has_many :goal_pinned_messages, dependent: :destroy
+  has_many :goals, through: :goal_pinned_messages
+
+  validates :display_text, presence: true, length: {maximum: MAX_DISPLAY_TEXT_LENGTH}
+  validates :message_id, uniqueness: true
+
+  # Pinned messages with no remaining active goals — safe to release.
+  #
+  # @return [ActiveRecord::Relation]
+  scope :orphaned, -> {
+    where.not(
+      "EXISTS (SELECT 1 FROM goal_pinned_messages gpm " \
+      "JOIN goals ON goals.id = gpm.goal_id " \
+      "WHERE gpm.pinned_message_id = pinned_messages.id " \
+      "AND goals.status = 'active')"
+    )
+  }
+
+  # @return [Integer] token cost estimate for viewport budget accounting
+  def token_cost
+    [(display_text.bytesize / Message::BYTES_PER_TOKEN.to_f).ceil, 1].max
+  end
+end