anima-core 0.2.1 → 1.0.0

data/app/jobs/count_event_tokens_job.rb

@@ -12,17 +12,28 @@ class CountEventTokensJob < ApplicationJob
   # @param event_id [Integer] the Event record to count tokens for
   def perform(event_id)
     event = Event.find(event_id)
-    return if event.token_count > 0
+    return if already_counted?(event)
 
     provider = Providers::Anthropic.new
     messages = [{role: event.api_role, content: event.payload["content"].to_s}]
 
     token_count = provider.count_tokens(
-      model: LLM::Client::DEFAULT_MODEL,
+      model: Anima::Settings.model,
       messages: messages
     )
 
-    # Atomic update: only write if still uncounted (avoids race with parallel jobs).
-    Event.where(id: event.id, token_count: 0).update_all(token_count: token_count)
+    # Guard against parallel jobs: reload and re-check before writing.
+    # Uses update! (not update_all) so {Event::Broadcasting} after_update_commit
+    # broadcasts the updated token count to connected clients.
+    event.reload
+    return if already_counted?(event)
+
+    event.update!(token_count: token_count)
+  end
+
+  private
+
+  def already_counted?(event)
+    event.token_count > 0
   end
 end

data/app/models/concerns/event/broadcasting.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+# Broadcasts Event records to connected WebSocket clients via ActionCable.
+# Follows the Turbo Streams pattern: events 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
+# maintain an ID-indexed store for efficient in-place updates (e.g. when
+# token counts arrive asynchronously from {CountEventTokensJob}).
+#
+# When a new event pushes old events out of the LLM's context window,
+# the broadcast includes `evicted_event_ids` so clients can remove
+# phantom messages that the agent no longer knows about.
+#
+# @example Create broadcast payload
+#   {
+#     "type" => "user_message", "content" => "hello", ...,
+#     "id" => 42, "action" => "create",
+#     "rendered" => { "basic" => { "role" => "user", "content" => "hello" } }
+#   }
+#
+# @example Broadcast with viewport evictions
+#   {
+#     "type" => "agent_message", "content" => "...", ...,
+#     "id" => 99, "action" => "create",
+#     "evicted_event_ids" => [101, 102, 103]
+#   }
+#
+# @example Update broadcast payload (e.g. token count arrives)
+#   {
+#     "type" => "user_message", "content" => "hello", ...,
+#     "id" => 42, "action" => "update",
+#     "rendered" => { "debug" => { "role" => "user", "content" => "hello", "tokens" => 15 } }
+#   }
+module Event::Broadcasting
+  extend ActiveSupport::Concern
+
+  ACTION_CREATE = "create"
+  ACTION_UPDATE = "update"
+
+  included do
+    after_create_commit :broadcast_create
+    after_update_commit :broadcast_update
+  end
+
+  private
+
+  def broadcast_create
+    broadcast_event(action: ACTION_CREATE)
+  end
+
+  def broadcast_update
+    broadcast_event(action: ACTION_UPDATE)
+  end
+
+  # Decorates the event 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:)
+    return unless session_id
+
+    session = Session.find_by(id: session_id)
+    return unless session
+
+    mode = session.view_mode
+    decorator = EventDecorator.for(self)
+    broadcast_payload = payload.merge("id" => id, "action" => action)
+
+    if decorator
+      broadcast_payload["rendered"] = {mode => decorator.render(mode)}
+    end
+
+    evicted_ids = session.recalculate_viewport!
+    broadcast_payload["evicted_event_ids"] = evicted_ids if evicted_ids.any?
+
+    ActionCable.server.broadcast("session_#{session_id}", broadcast_payload)
+  end
+end

data/app/models/event.rb

@@ -16,9 +16,12 @@
 # @!attribute tool_use_id
 #   @return [String, nil] Anthropic-assigned ID correlating tool_call and tool_response
 class Event < ApplicationRecord
+  include Event::Broadcasting
+
   TYPES = %w[system_message user_message agent_message tool_call tool_response].freeze
   LLM_TYPES = %w[user_message agent_message].freeze
-  CONTEXT_TYPES = %w[user_message agent_message tool_call tool_response].freeze
+  CONTEXT_TYPES = %w[system_message user_message agent_message tool_call tool_response].freeze
+  PENDING_STATUS = "pending"
 
   ROLE_MAP = {"user_message" => "user", "agent_message" => "assistant"}.freeze
 
@@ -43,6 +46,17 @@ class Event < ApplicationRecord
   #   @return [ActiveRecord::Relation]
   scope :context_events, -> { where(event_type: CONTEXT_TYPES) }
 
+  # @!method self.pending
+  #   User messages queued during active agent processing, not yet sent to LLM.
+  #   @return [ActiveRecord::Relation]
+  scope :pending, -> { where(status: PENDING_STATUS) }
+
+  # @!method self.deliverable
+  #   Events 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) }
+
   # Maps event_type to the Anthropic Messages API role.
   # @return [String] "user" or "assistant"
   def api_role
@@ -59,6 +73,11 @@ class Event < ApplicationRecord
     event_type.in?(CONTEXT_TYPES)
   end
 
+  # @return [Boolean] true if this is a pending message not yet sent to the LLM
+  def pending?
+    status == PENDING_STATUS
+  end
+
   # Heuristic token estimate: ~4 bytes per token for English prose.
   # Tool events are estimated from the full payload JSON since tool_input
   # and tool metadata contribute to token count. Messages use content only.

data/app/models/goal.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# A persistent objective tracked by the analytical brain during a session.
+# Goals form a two-level hierarchy: root goals represent high-level
+# objectives (semantic episodes), while sub-goals are TODO-style steps
+# rendered as checklist items in the agent's system prompt.
+#
+# The analytical brain creates and completes goals; the main agent sees
+# them in its context window but never manages them directly.
+class Goal < ApplicationRecord
+  STATUSES = %w[active completed].freeze
+
+  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
+
+  validates :description, presence: true
+  validates :status, inclusion: {in: STATUSES}
+  validate :parent_goal_belongs_to_same_session, if: :parent_goal
+  validate :parent_goal_is_root, if: :parent_goal
+
+  scope :active, -> { where(status: "active") }
+  scope :completed, -> { where(status: "completed") }
+  scope :root, -> { where(parent_goal_id: nil) }
+
+  after_commit :broadcast_goals_update
+
+  # @return [Boolean] true if this goal has been completed
+  def completed? = status == "completed"
+
+  # @return [Boolean] true if this is a root goal (no parent)
+  def root? = !parent_goal_id
+
+  # Cascades completion to all active sub-goals. Called when a root goal
+  # is finished — remaining sub-items are implicitly resolved because
+  # the semantic episode that spawned them has ended.
+  #
+  # Uses +update_all+ to avoid N per-record +after_commit+ broadcasts;
+  # the caller ({AnalyticalBrain::Tools::FinishGoal}) wraps the whole
+  # operation in a transaction so the root goal's single broadcast
+  # includes the cascaded state.
+  #
+  # @return [void]
+  def cascade_completion!
+    now = Time.current
+    sub_goals.active.update_all(status: "completed", completed_at: now, updated_at: now)
+  end
+
+  # Serializes this goal for ActionCable broadcast and TUI display.
+  # Includes nested sub-goals for root goals.
+  #
+  # @return [Hash{String => Object}] with keys "id", "description", "status",
+  #   and "sub_goals" (Array of Hash with "id", "description", "status")
+  def as_summary
+    {
+      "id" => id,
+      "description" => description,
+      "status" => status,
+      "sub_goals" => sub_goals.map { |sub|
+        {"id" => sub.id, "description" => sub.description, "status" => sub.status}
+      }
+    }
+  end
+
+  private
+
+  def parent_goal_belongs_to_same_session
+    return if parent_goal.session_id == session_id
+
+    errors.add(:parent_goal, "must belong to the same session")
+  end
+
+  def parent_goal_is_root
+    return unless parent_goal.parent_goal_id
+
+    errors.add(:parent_goal, "cannot nest deeper than two levels")
+  end
+
+  # Broadcasts goal changes to all clients subscribed to this session.
+  # Mirrors the Session#broadcast_active_skills_update pattern so the
+  # TUI info panel updates reactively.
+  #
+  # @return [void]
+  def broadcast_goals_update
+    ActionCable.server.broadcast("session_#{session_id}", {
+      "action" => "goals_updated",
+      "session_id" => session_id,
+      "goals" => session.goals_summary
+    })
+  end
+end