anima-core 1.4.0 → 1.5.0

data/app/models/goal.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-# A persistent objective tracked by the analytical brain during a session.
+# A persistent objective tracked by Melete 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
+# Melete 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
@@ -26,7 +26,7 @@ class Goal < ApplicationRecord
   scope :root, -> { where(parent_goal_id: nil) }
 
   # @!method self.not_evicted
-  #   Goals still visible in context (not yet evicted by the analytical brain).
+  #   Goals still visible in context (not yet evicted by Melete).
   #   @return [ActiveRecord::Relation]
   scope :not_evicted, -> { where(evicted_at: nil) }
 
@@ -37,7 +37,8 @@ class Goal < ApplicationRecord
   scope :evictable, -> { completed.where(evicted_at: nil) }
 
   after_commit :broadcast_goals_update
-  after_commit :schedule_passive_recall, on: [:create, :update]
+  after_commit :emit_goal_created, on: :create
+  after_commit :emit_goal_updated, on: :update, if: :saved_change_to_description?
 
   # @return [Boolean] true if this goal has been completed
   def completed? = status == "completed"
@@ -56,7 +57,7 @@ class Goal < ApplicationRecord
   # 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
+  # the caller ({Melete::Tools::FinishGoal}) wraps the whole
   # operation in a transaction so the root goal's single broadcast
   # includes the cascaded state.
   #
@@ -107,14 +108,24 @@ class Goal < ApplicationRecord
     errors.add(:parent_goal, "cannot nest deeper than two levels")
   end
 
-  # Triggers passive recall when goals change so relevant memories
-  # surface in the viewport automatically.
+  # Announces a freshly created goal so the active drain pipeline can
+  # decide whether Mneme should recall against the updated goal set.
+  # Only {MeleteEnrichmentJob}'s scoped listener observes these events;
+  # outside of a Melete run they are silently dropped.
   #
   # @return [void]
-  def schedule_passive_recall
-    return if session.sub_agent?
+  def emit_goal_created
+    Events::Bus.emit(Events::GoalCreated.new(session_id: session_id, goal_id: id))
+  end
 
-    PassiveRecallJob.perform_later(session_id)
+  # Announces a description-level change to an existing goal. Status-only
+  # updates (finish, cascade, mark_goal_completed) are filtered out by the
+  # +saved_change_to_description?+ guard on the callback — a completed goal
+  # carries no new search seed for Mneme.
+  #
+  # @return [void]
+  def emit_goal_updated
+    Events::Bus.emit(Events::GoalUpdated.new(session_id: session_id, goal_id: id))
   end
 
   # Broadcasts goal changes to all clients subscribed to this session.

data/app/models/message.rb

@@ -7,6 +7,10 @@
 # Not to be confused with {Events::Base} (transient bus signals).
 # Messages persist to SQLite; events flow through the bus and are gone.
 #
+# After commit, emits {Events::MessageCreated} and {Events::MessageUpdated}
+# lifecycle events so subscribers ({Events::Subscribers::MessageBroadcaster},
+# {Events::Subscribers::MnemeScheduler}) can react without coupling.
+#
 # @!attribute message_type
 #   @return [String] one of {TYPES}: system_message, user_message,
 #     agent_message, tool_call, tool_response
@@ -15,17 +19,18 @@
 # @!attribute timestamp
 #   @return [Integer] nanoseconds since epoch (Process::CLOCK_REALTIME)
 # @!attribute token_count
-#   @return [Integer] cached token count for this message's payload (0 until counted)
+#   @return [Integer] token count for this message's payload. Seeded with
+#     a local estimate on create and later refined by {CountTokensJob} using
+#     the real Anthropic tokenizer. Always positive — never zero or nil.
 # @!attribute tool_use_id
 #   @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 messages)
 class Message < ApplicationRecord
-  include Message::Broadcasting
+  include TokenEstimation
 
   TYPES = %w[system_message user_message agent_message tool_call tool_response].freeze
   LLM_TYPES = %w[user_message agent_message].freeze
-  CONTEXT_TYPES = %w[system_message user_message agent_message tool_call tool_response].freeze
   CONVERSATION_TYPES = %w[user_message agent_message system_message].freeze
   THINK_TOOL = "think"
   # Message types that require a tool_use_id to pair call with response.
@@ -33,21 +38,11 @@ class Message < ApplicationRecord
 
   ROLE_MAP = {"user_message" => "user", "agent_message" => "assistant"}.freeze
 
-  # Heuristic: average bytes per token for English prose.
-  BYTES_PER_TOKEN = 4
-
   # Synthetic ID for system prompt entries in the TUI message store.
   # Real message IDs are positive integers from the database, so 0
   # is safe for deduplication without collision risk.
   SYSTEM_PROMPT_ID = 0
 
-  # Estimates token count from a byte size using the {BYTES_PER_TOKEN} heuristic.
-  # @param bytesize [Integer] number of bytes
-  # @return [Integer] estimated token count (at least 1)
-  def self.estimate_token_count(bytesize)
-    [(bytesize / BYTES_PER_TOKEN.to_f).ceil, 1].max
-  end
-
   belongs_to :session
   has_many :pinned_messages, dependent: :destroy
 
@@ -57,17 +52,23 @@ class Message < ApplicationRecord
   # Anthropic requires every tool_use to have a matching tool_result with the same ID
   validates :tool_use_id, presence: true, if: -> { message_type.in?(TOOL_TYPES) }
 
-  after_create :schedule_token_count, if: :llm_message?
+  after_create_commit :emit_created_event
+  after_update_commit :emit_updated_event
 
   # @!method self.llm_messages
   #   Messages that represent conversation turns sent to the LLM API.
   #   @return [ActiveRecord::Relation]
   scope :llm_messages, -> { where(message_type: LLM_TYPES) }
 
-  # @!method self.context_messages
-  #   Messages included in the LLM context window (conversation + tool interactions).
+  # @!method self.conversation_or_think
+  #   Conversation messages (user/agent/system) and think tool_calls —
+  #   the messages Mneme treats as boundary-eligible.
   #   @return [ActiveRecord::Relation]
-  scope :context_messages, -> { where(message_type: CONTEXT_TYPES) }
+  scope :conversation_or_think, -> {
+    where(message_type: CONVERSATION_TYPES)
+      .or(where(message_type: "tool_call")
+        .where("json_extract(payload, '$.tool_name') = ?", THINK_TOOL))
+  }
 
   # Maps message_type to the Anthropic Messages API role.
   # @return [String] "user" or "assistant"
@@ -75,16 +76,6 @@ class Message < ApplicationRecord
     ROLE_MAP.fetch(message_type)
   end
 
-  # @return [Boolean] true if this message represents an LLM conversation turn
-  def llm_message?
-    message_type.in?(LLM_TYPES)
-  end
-
-  # @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 conversation message (user/agent/system)
   #   or a think tool_call — the messages Mneme treats as "conversation" for boundary tracking
   def conversation_or_think?
@@ -92,23 +83,43 @@ class Message < ApplicationRecord
       (message_type == "tool_call" && payload["tool_name"] == THINK_TOOL)
   end
 
-  # Heuristic token estimate: ~4 bytes per token for English prose.
-  # Tool messages are estimated from the full payload JSON since tool_input
-  # and tool metadata contribute to token count. Messages use content only.
+  # String fed to the token estimator and the remote tokenizer. Tool
+  # messages serialize the full payload as JSON so +tool_name+, +tool_input+,
+  # and +tool_use_id+ contribute to the count; conversation messages use
+  # the content field only.
   #
-  # @return [Integer] estimated token count (at least 1)
-  def estimate_tokens
-    text = if message_type.in?(TOOL_TYPES)
+  # @return [String]
+  def tokenization_text
+    if message_type.in?(TOOL_TYPES)
       payload.to_json
     else
       payload["content"].to_s
     end
-    self.class.estimate_token_count(text.bytesize)
+  end
+
+  # Draper hook: picks the concrete decorator subclass based on
+  # {#message_type}. Overrides {Draper::Decoratable#decorator_class},
+  # which would otherwise default to the abstract {MessageDecorator}
+  # base class. Called implicitly by +message.decorate+.
+  #
+  # @return [Class] a {MessageDecorator} subclass
+  def decorator_class
+    case message_type
+    when "user_message" then UserMessageDecorator
+    when "agent_message" then AgentMessageDecorator
+    when "system_message" then SystemMessageDecorator
+    when "tool_call" then ToolCallDecorator
+    when "tool_response" then ToolResponseDecorator
+    end
   end
 
   private
 
-  def schedule_token_count
-    CountMessageTokensJob.perform_later(id)
+  def emit_created_event
+    Events::Bus.emit(Events::MessageCreated.new(self))
+  end
+
+  def emit_updated_event
+    Events::Bus.emit(Events::MessageUpdated.new(self))
   end
 end

data/app/models/pending_message.rb

@@ -5,10 +5,10 @@
 # message stream and have no database ID that could interleave with
 # tool_call/tool_response pairs.
 #
-# Created when a message arrives while the session is processing.
-# Promoted to a real {Message} (delete + create in transaction) when
-# the current agent loop completes, giving the new message an ID that
-# naturally follows the tool batch.
+# Entry point of the event-driven drain pipeline. Every inbound
+# message destined for the LLM — user input, tool responses,
+# sub-agent replies, Mneme recalls, Melete skills/goals — lands here
+# first, then gets promoted into a real {Message} by {DrainJob}.
 #
 # Each pending message knows its source (+source_type+, +source_name+)
 # and how to serialize itself for the LLM conversation via {#to_llm_messages}.
@@ -16,30 +16,38 @@
 # goal events) become synthetic tool_use/tool_result pairs so the LLM sees
 # "a tool I invoked returned a result" rather than "a user wrote me."
 #
+# Classifies itself for the pipeline via +kind+ (+active+ triggers the
+# drain loop, +background+ enriches context silently) and +message_type+
+# (selects which pipeline event to emit on create).
+#
 # @see Session#enqueue_user_message
-# @see Session#promote_pending_messages!
+# @see DrainJob — promotes PMs into Messages
+# @see Events::StartMelete
+# @see Events::StartProcessing
 class PendingMessage < ApplicationRecord
-  # Synthetic tool names used in tool_use/tool_result pairs injected into
-  # the parent LLM conversation when non-user messages are promoted.
-  # These tools don't exist in the agent's registry — the agent sees
-  # them as its own past actions (phantom tool calls).
-  SUBAGENT_TOOL = "subagent_message"
-  RECALL_SKILL_TOOL = "recall_skill"
-  RECALL_WORKFLOW_TOOL = "recall_workflow"
-  RECALL_MEMORY_TOOL = "recall_memory"
-  RECALL_GOAL_TOOL = "recall_goal"
+  # Phantom tool names follow the `from_<sender>` convention: the prefix
+  # tells the LLM these are messages delivered to it by its sisters or
+  # sub-agents, not tools it invoked. Melete's contributions carry the
+  # type in the suffix so the viewport query can filter by kind.
+  MELETE_SKILL_TOOL = "from_melete_skill"
+  MELETE_WORKFLOW_TOOL = "from_melete_workflow"
+  MELETE_GOAL_TOOL = "from_melete_goal"
+  MNEME_TOOL = "from_mneme"
 
   # Source types that produce phantom tool_use/tool_result pairs on promotion.
   # User messages produce plain text blocks instead.
   PHANTOM_PAIR_TYPES = %w[subagent skill workflow recall goal].freeze
 
-  # Maps each phantom pair source type to its synthetic tool name.
+  # Maps each phantom pair source type to a lambda that builds its
+  # synthetic tool name. Each Melete contribution carries the type in
+  # its suffix; recalled memories come from Mneme; sub-agents encode
+  # their nickname directly (e.g. `from_sleuth`).
   PHANTOM_TOOL_NAMES = {
-    "subagent" => SUBAGENT_TOOL,
-    "skill" => RECALL_SKILL_TOOL,
-    "workflow" => RECALL_WORKFLOW_TOOL,
-    "recall" => RECALL_MEMORY_TOOL,
-    "goal" => RECALL_GOAL_TOOL
+    "subagent" => ->(name) { "from_#{name}" },
+    "skill" => ->(_) { MELETE_SKILL_TOOL },
+    "workflow" => ->(_) { MELETE_WORKFLOW_TOOL },
+    "recall" => ->(_) { MNEME_TOOL },
+    "goal" => ->(_) { MELETE_GOAL_TOOL }
   }.freeze
 
   # Maps each phantom pair source type to a lambda building its tool input.
@@ -51,13 +59,65 @@ class PendingMessage < ApplicationRecord
     "goal" => ->(name) { {goal_id: name.to_i} }
   }.freeze
 
+  # Every message_type has a defined drain-pipeline role. +active+ types
+  # trigger the drain loop when the session is idle; +background+ types
+  # enrich context silently and ride the next active turn into the LLM.
+  # {#kind} is derived from this map in {#derive_kind} — callers only
+  # supply +message_type+.
+  MESSAGE_TYPE_KINDS = {
+    "user_message" => "active",
+    "tool_response" => "active",
+    "subagent" => "active",
+    "from_mneme" => "background",
+    "from_melete_skill" => "background",
+    "from_melete_workflow" => "background",
+    "from_melete_goal" => "background"
+  }.freeze
+
+  MESSAGE_TYPES = MESSAGE_TYPE_KINDS.keys.freeze
+
+  # Routes active message types to the event that begins the drain pipeline.
+  # User messages enter through Melete (skill/workflow/goal preparation);
+  # Mneme then runs conditionally only when Melete actually mutates goals
+  # (set_goal / update_goal), so recall always fires against fresh goals.
+  # Tool responses and sub-agent deliveries bypass enrichment and go
+  # straight to the drain loop. Background message types route to nothing
+  # — they wait in the mailbox until an active turn drains them.
+  MESSAGE_TYPE_ROUTES = {
+    "user_message" => Events::StartMelete,
+    "tool_response" => Events::StartProcessing,
+    "subagent" => Events::StartProcessing
+  }.freeze
+
   belongs_to :session
 
+  # In-memory id of the +Message+ this PM becomes on {#promote!}. Not
+  # persisted — the PM row is destroyed as part of the promotion transaction.
+  # Used by {Session#release_with_bounce_back} to destroy the exact message
+  # that should bounce, instead of guessing from +messages.last+ (which could
+  # race under parallel drains).
+  attr_accessor :promoted_message_id
+
+  enum :kind, {background: "background", active: "active"}
+
+  before_validation :derive_kind, if: :message_type
+
   validates :content, presence: true
-  validates :source_type, inclusion: {in: %w[user subagent skill workflow recall goal]}
   validates :source_name, presence: true, unless: :user?
+  validates :message_type, presence: true, inclusion: {in: MESSAGE_TYPES}
+  validates :tool_use_id, presence: true, if: -> { message_type == "tool_response" }
+
+  # Tool responses take priority over other active messages: they complete
+  # a tool round the LLM is waiting on, so promoting them first preserves
+  # the tool_use/tool_result pairing in the conversation. Other actives
+  # (user messages, sub-agent replies) wait their FIFO turn behind the
+  # completion.
+  scope :ordered_for_drain, -> {
+    active.order(Arel.sql("message_type = 'tool_response' DESC")).order(:created_at)
+  }
 
   after_create_commit :broadcast_created
+  after_create_commit :route_to_event_bus
   after_destroy_commit :broadcast_removed
 
   # @return [Boolean] true when this is a plain user message
@@ -95,12 +155,69 @@ class PendingMessage < ApplicationRecord
     source_type.in?(PHANTOM_PAIR_TYPES)
   end
 
+  # Draper hook: picks the concrete decorator subclass based on
+  # {#message_type}. Mirrors {Message#decorator_class} so each PM type
+  # renders with the same visual treatment as its promoted counterpart,
+  # marked dimmed via +status: "pending"+.
+  #
+  # PMs are the universal intake queue — every new message_type added
+  # under #427 lands here first. Raises on unmapped types so a missing
+  # decorator surfaces immediately as a hard failure instead of a
+  # silent nil that breaks downstream rendering.
+  #
+  # @return [Class] a {PendingMessageDecorator} subclass
+  # @raise [ArgumentError] if no decorator is registered for the message_type
+  def decorator_class
+    case message_type
+    when "user_message" then PendingUserMessageDecorator
+    when "tool_response" then PendingToolResponseDecorator
+    when "subagent" then PendingSubagentDecorator
+    when "from_mneme" then PendingFromMnemeDecorator
+    when "from_melete_skill" then PendingFromMeleteSkillDecorator
+    when "from_melete_workflow" then PendingFromMeleteWorkflowDecorator
+    when "from_melete_goal" then PendingFromMeleteGoalDecorator
+    else raise ArgumentError, "No decorator for PendingMessage message_type: #{message_type.inspect}"
+    end
+  end
+
+  # Promotes this PendingMessage into the session's conversation history.
+  # Dispatches on +message_type+: tool responses become +tool_response+
+  # Messages, user messages become +user_message+ Messages, phantom pair
+  # types (sub-agent, skill, workflow, recall, goal) become synthetic
+  # tool_use/tool_result pairs. The PM row is destroyed in the same
+  # transaction so partial promotion can never leave a stray mailbox entry.
+  #
+  # For promotions that yield a single Message, {#promoted_message_id}
+  # captures the new record's id — callers can then act on that specific
+  # message (e.g. {Session#release_with_bounce_back}) without guessing.
+  #
+  # @return [void]
+  def promote!
+    session.transaction do
+      if message_type == "tool_response"
+        self.promoted_message_id = promote_as_tool_response!.id
+      elsif message_type == "user_message"
+        self.promoted_message_id = session.create_user_message(
+          display_content,
+          source_type: source_type,
+          source_name: source_name
+        ).id
+      elsif phantom_pair?
+        promote_as_phantom_pair!
+      else
+        raise "PendingMessage ##{id} cannot promote: message_type=#{message_type.inspect}"
+      end
+      destroy!
+    end
+  end
+
   # Phantom tool name for DB persistence and LLM injection.
-  # Each phantom pair source type maps to a synthetic tool name.
+  # Each phantom pair source type maps to a synthetic tool name via
+  # {PHANTOM_TOOL_NAMES} — a lambda so sub-agent names can flow through.
   #
   # @return [String] phantom tool name
   def phantom_tool_name
-    PHANTOM_TOOL_NAMES.fetch(source_type)
+    PHANTOM_TOOL_NAMES.fetch(source_type).call(source_name)
   end
 
   # Phantom tool input hash for DB persistence and LLM injection.
@@ -144,8 +261,130 @@ class PendingMessage < ApplicationRecord
     build_phantom_pair(phantom_tool_name, phantom_tool_input)
   end
 
+  # Emits the event that kicks off the drain pipeline for active messages
+  # whenever the session is currently claimable. Claimability is delegated
+  # to the AASM via +may_start_processing?+ — true from +:idle+ always,
+  # true from +:executing+ only once +tool_round_complete?+ holds. This
+  # lets a tool_response PM landing mid-round wake the drain only when
+  # its sibling responses are all present.
+  #
+  # Background messages never trigger; active messages landing while the
+  # session is unclaimable queue silently —
+  # {Session#wake_drain_pipeline_if_pending} re-invokes this on the next
+  # transition into +:idle+.
+  #
+  # Also fires from +after_create_commit+ so freshly enqueued PMs route
+  # themselves on persistence.
+  def route_to_event_bus
+    return unless active?
+    return unless session.may_start_processing?
+
+    event_class = MESSAGE_TYPE_ROUTES.fetch(message_type)
+    Events::Bus.emit(event_class.new(session_id: session_id, pending_message_id: id))
+  end
+
+  # Builds the structured +pending_message_created+ payload for transmit/
+  # broadcast paths. Wraps the per-mode decorator output in the +rendered+
+  # key so the TUI's existing +extract_rendered+ pipeline applies.
+  #
+  # Required arg — callers always know the session view_mode. A default
+  # of +session.view_mode+ would trigger a SELECT per +after_create_commit+
+  # when the association isn't preloaded.
+  #
+  # The raw +content+ field is intentionally absent: decorators decide
+  # what crosses the wire per view_mode (e.g. background PMs return nil
+  # in basic so the user doesn't see internal pipeline noise). Sending
+  # raw content alongside +rendered+ would undercut that boundary.
+  #
+  # @param mode [String] view mode for decoration
+  # @return [Hash] payload ready for ActionCable transmission
+  def broadcast_payload(mode)
+    {
+      "action" => "pending_message_created",
+      "pending_message_id" => id,
+      "message_type" => message_type,
+      "rendered" => {mode => decorate.render(mode)}
+    }
+  end
+
   private
 
+  # Persists a +tool_response+ Message for this PM and returns it.
+  # Mirrors the tool_use_id / payload shape emitted by
+  # {Events::Subscribers::LLMResponseHandler} for the paired +tool_call+.
+  #
+  # @return [Message]
+  def promote_as_tool_response!
+    session.messages.create!(
+      message_type: "tool_response",
+      tool_use_id: tool_use_id,
+      payload: {
+        "tool_name" => source_name,
+        "tool_use_id" => tool_use_id,
+        "content" => content,
+        "success" => success
+      },
+      timestamp: Time.current.to_ns,
+      token_count: TokenEstimation.estimate_token_count(content)
+    )
+  end
+
+  # Persists a synthetic +tool_call+/+tool_response+ Message pair so the
+  # LLM sees this contribution (sub-agent delivery, Melete skill/workflow/
+  # goal, Mneme recall) as a past tool invocation of its own. Keeps the
+  # system prompt stable for prompt caching — phantom pairs flow through
+  # the sliding-window conversation instead.
+  #
+  # @return [void]
+  def promote_as_phantom_pair!
+    tool_name = phantom_tool_name
+    uid = "#{tool_name}_#{id}"
+    now = Time.current.to_ns
+
+    session.messages.create!(
+      message_type: "tool_call",
+      tool_use_id: uid,
+      payload: {
+        "tool_name" => tool_name,
+        "tool_use_id" => uid,
+        "tool_input" => phantom_tool_input.stringify_keys,
+        "content" => display_content.lines.first.chomp
+      },
+      timestamp: now,
+      token_count: Mneme::TOOL_PAIR_OVERHEAD_TOKENS
+    )
+
+    session.messages.create!(
+      message_type: "tool_response",
+      tool_use_id: uid,
+      payload: {
+        "tool_name" => tool_name,
+        "tool_use_id" => uid,
+        "content" => content,
+        "success" => true
+      },
+      timestamp: now,
+      token_count: TokenEstimation.estimate_token_count(content)
+    )
+
+    restore_subagent_hud_visibility! if subagent?
+  end
+
+  # Flips the delivering sub-agent back to +hud_visible: true+ when the
+  # phantom pair we just persisted reintroduces a trace. A subsequent
+  # eviction that passes every trace will hide the sub-agent again via
+  # {Mneme::Runner#refresh_subagent_visibility}.
+  #
+  # Re-broadcasts the parent's children list on flip so the TUI adds the
+  # HUD entry back without waiting for the next AASM state change.
+  def restore_subagent_hud_visibility!
+    child = session.child_sessions.find_by(name: source_name)
+    return unless child && !child.hud_visible
+
+    child.update_column(:hud_visible, true)
+    child.broadcast_children_update_to_parent
+  end
+
   # Builds a phantom tool_use/tool_result message pair.
   # Follows the same format for all non-user source types — the only
   # difference is the tool name and input hash.
@@ -171,13 +410,11 @@ class PendingMessage < ApplicationRecord
   end
 
   # Broadcasts a pending message appearance so TUI clients render the
-  # dimmed indicator immediately.
+  # type-specific dimmed indicator immediately. Includes the decorated
+  # payload for the session's current view mode so the TUI can dispatch
+  # by message type without a second round-trip.
   def broadcast_created
-    ActionCable.server.broadcast("session_#{session_id}", {
-      "action" => "pending_message_created",
-      "pending_message_id" => id,
-      "content" => content
-    })
+    ActionCable.server.broadcast("session_#{session_id}", broadcast_payload(session.view_mode))
   end
 
   # Broadcasts pending message removal so TUI clients clear the entry.
@@ -188,4 +425,14 @@ class PendingMessage < ApplicationRecord
       "pending_message_id" => id
     })
   end
+
+  # Populates +kind+ from {MESSAGE_TYPE_KINDS} so callers only need to
+  # supply +message_type+. The mapping is the single source of truth for
+  # whether a message type triggers the drain loop or rides along as
+  # enrichment. Guarded by +if: :message_type+ on the callback — rows
+  # without a +message_type+ fail validation explicitly rather than
+  # crashing here.
+  def derive_kind
+    self.kind = MESSAGE_TYPE_KINDS.fetch(message_type)
+  end
 end

data/app/models/pinned_message.rb

@@ -10,7 +10,12 @@
 #
 # @!attribute display_text
 #   @return [String] truncated message content (~200 chars) shown in the Goals section
+# @!attribute token_count
+#   @return [Integer] token count of {#display_text}. Seeded with a local
+#     estimate on create and later refined by {CountTokensJob}.
 class PinnedMessage < ApplicationRecord
+  include TokenEstimation
+
   # Display text limit — enough to recognize content, cheap on tokens.
   MAX_DISPLAY_TEXT_LENGTH = 200
 
@@ -34,8 +39,8 @@ class PinnedMessage < ApplicationRecord
     )
   }
 
-  # @return [Integer] token cost estimate for viewport budget accounting
-  def token_cost
-    [(display_text.bytesize / Message::BYTES_PER_TOKEN.to_f).ceil, 1].max
+  # @return [String] truncated display text used for token estimation and counting
+  def tokenization_text
+    display_text.to_s
   end
 end