anima-core 1.4.0 → 1.5.0

data/app/models/session.rb

@@ -7,10 +7,55 @@
 # Sessions form a hierarchy: a main session can spawn child sessions
 # (sub-agents) that inherit the parent's viewport context at fork time.
 class Session < ApplicationRecord
+  include AASM
+
   class MissingSoulError < StandardError; end
 
   VIEW_MODES = %w[basic verbose debug].freeze
 
+  # Non-default AASM options:
+  # - +whiny_transitions: false+ makes invalid transitions return +false+
+  #   instead of raising. {DrainJob} depends on this: +start_processing!+
+  #   returning +false+ signals that the session is busy (+:awaiting+) or
+  #   that the current tool round is still incomplete, so the current
+  #   invocation exits silently.
+  # - +no_direct_assignment: true+ blocks +session.aasm_state = ...+, forcing
+  #   every transition through a named event so guards always run.
+  # - +requires_lock: true+ wraps each transition in a pessimistic row lock
+  #   (+SELECT FOR UPDATE+ on PostgreSQL, +BEGIN IMMEDIATE+ on SQLite) so
+  #   two workers racing +start_processing!+ on a parallel tool-use turn
+  #   can't both succeed — the loser reads the updated +:awaiting+ state
+  #   and bails silently.
+  aasm whiny_transitions: false, no_direct_assignment: true, requires_lock: true do
+    after_all_events :emit_state_change
+    after_all_events :clear_interrupt_flag_if_idle
+    after_all_events :wake_drain_pipeline_if_pending
+
+    state :idle, initial: true
+    state :awaiting
+    state :executing
+
+    # Drain claim. Two transitions, one event:
+    # - From +:idle+, the session is fresh — claim unconditionally.
+    # - From +:executing+, only claim once every +tool_use_id+ from the
+    #   latest assistant turn has a matching tool_response (Message or
+    #   PendingMessage). This collapses "tool round complete" and "drain
+    #   claims" into one atomic, lock-protected transition so the LLM
+    #   never sees a partial round.
+    event :start_processing do
+      transitions from: :idle, to: :awaiting
+      transitions from: :executing, to: :awaiting, guard: :tool_round_complete?
+    end
+
+    event :tool_received do
+      transitions from: :awaiting, to: :executing
+    end
+
+    event :response_complete do
+      transitions from: :awaiting, to: :idle
+    end
+  end
+
   attribute :view_mode, :string, default: -> { Anima::Settings.default_view_mode }
 
   serialize :granted_tools, coder: JSON
@@ -28,75 +73,55 @@ class Session < ApplicationRecord
   validates :name, length: {maximum: 255}, allow_nil: true
 
   after_update_commit :broadcast_name_update, if: :saved_change_to_name?
-  after_update_commit :broadcast_active_skills_update, if: :saved_change_to_active_skills?
-  after_update_commit :broadcast_active_workflow_update, if: :saved_change_to_active_workflow?
 
   scope :recent, ->(limit = 10) { order(updated_at: :desc).limit(limit) }
   scope :root_sessions, -> { where(parent_session_id: nil) }
-  scope :processing_children_of, ->(parent_id) { where(parent_session_id: parent_id, processing: true) }
-
-  # Cycles to the next view mode: basic → verbose → debug → basic.
-  #
-  # @return [String] the next view mode in the cycle
-  def next_view_mode
-    current_index = VIEW_MODES.index(view_mode) || 0
-    VIEW_MODES[(current_index + 1) % VIEW_MODES.size]
-  end
+  # Sessions currently working on behalf of a human — any non-idle AASM state.
+  scope :processing, -> { awaiting.or(executing) }
 
   # @return [Boolean] true if this session is a sub-agent (has a parent)
   def sub_agent?
     parent_session_id.present?
   end
 
-  # Checks whether the Mneme terminal message has left the viewport and
-  # enqueues {MnemeJob} when it has. On the first message of a new session,
-  # initializes the boundary pointer.
+  # Checks whether the Mneme boundary has left the viewport and enqueues
+  # {MnemeJob} when it has. Delegates initial boundary placement to
+  # {#initialize_mneme_boundary!} on the first call.
   #
-  # The terminal message is always a conversation message (user/agent message
-  # or think tool_call), never a bare tool_call/tool_response.
+  # The boundary has "left the viewport" when the cumulative token cost
+  # of everything from the boundary to the newest message exceeds the
+  # budget — a single SUM aggregate, no window function needed.
   #
   # @return [void]
   def schedule_mneme!
     return if sub_agent?
 
-    # Initialize boundary on first conversation message
     if mneme_boundary_message_id.nil?
-      first_conversation = messages
-        .where(message_type: Message::CONVERSATION_TYPES)
-        .order(:id).first
-      first_conversation ||= messages
-        .where(message_type: "tool_call")
-        .detect { |msg| msg.payload["tool_name"] == Message::THINK_TOOL }
-
-      if first_conversation
-        update_column(:mneme_boundary_message_id, first_conversation.id)
-      end
+      initialize_mneme_boundary!
       return
     end
 
-    # Check if boundary message has left the viewport
-    return if viewport_message_ids.include?(mneme_boundary_message_id)
+    tokens_since_boundary = messages
+      .where("messages.id >= ?", mneme_boundary_message_id)
+      .sum(:token_count)
+    return if tokens_since_boundary <= effective_token_budget
 
     MnemeJob.perform_later(id)
   end
 
-  # Enqueues the analytical brain to perform background maintenance on
-  # this session. Currently handles session naming; future phases add
-  # skill activation, goal tracking, and memory.
+  # Places the initial Mneme boundary at the oldest eligible message in
+  # the session — the top of the raw window, from which Mneme will start
+  # compressing downward once that message drifts out of the viewport.
+  # Eligible messages are conversation messages (user/agent/system) and
+  # think tool_calls, considered on equal footing; bare tool_call or
+  # tool_response messages are never eligible.
   #
-  # Runs after the first exchange and periodically as the conversation
-  # evolves, so the name stays relevant to the current topic.
+  # No-op when the session has no eligible messages yet.
   #
   # @return [void]
-  def schedule_analytical_brain!
-    return if sub_agent?
-
-    count = messages.llm_messages.count
-    return if count < 2
-    # Already named — only regenerate at interval boundaries (30, 60, 90, …)
-    return if name.present? && (count % Anima::Settings.name_generation_interval != 0)
-
-    AnalyticalBrainJob.perform_later(id)
+  def initialize_mneme_boundary!
+    first_id = messages.conversation_or_think.order(:id).pick(:id)
+    update_column(:mneme_boundary_message_id, first_id) if first_id
   end
 
   # Token budget appropriate for this session type.
@@ -106,157 +131,176 @@ class Session < ApplicationRecord
     sub_agent? ? Anima::Settings.subagent_token_budget : Anima::Settings.token_budget
   end
 
-  # Returns the messages currently visible in the LLM context window.
-  # Walks messages newest-first and includes them until the token budget
-  # is exhausted. Messages are full-size or excluded entirely.
+  # Returns the messages currently visible in the LLM context window as a
+  # composable AR relation. Selects own messages above the Mneme boundary
+  # whose cumulative token count (walked newest-first) fits within the
+  # budget. The newest message is always included even when it alone
+  # exceeds the budget. Messages are full-size or excluded entirely.
   #
-  # Pending messages live in a separate table ({PendingMessage}) and never
-  # appear in this viewport — they are promoted to real messages before
-  # the agent processes them.
+  # The selection runs as a single SQL query using a window function
+  # ({+SUM() OVER+}). Older messages have been compressed into snapshots
+  # and no longer participate in the viewport. Pending messages live in a
+  # separate table ({PendingMessage}) and never appear here — they are
+  # promoted to real messages before the agent processes them.
   #
   # @param token_budget [Integer] maximum tokens to include (positive)
-  # @return [Array<Message>] chronologically ordered
+  # @return [ActiveRecord::Relation<Message>] chronologically ordered by id
   def viewport_messages(token_budget: effective_token_budget)
-    select_messages(own_message_scope, budget: token_budget)
-  end
+    scope = messages
+    scope = scope.where("messages.id >= ?", mneme_boundary_message_id) if mneme_boundary_message_id
 
-  # Recalculates the viewport and returns IDs of messages evicted since the
-  # last snapshot. Updates the stored viewport_message_ids atomically.
-  # Piggybacks on message broadcasts to notify clients which messages left
-  # the LLM's context window.
-  #
-  # @return [Array<Integer>] IDs of messages no longer in the viewport
-  def recalculate_viewport!
-    new_ids = viewport_messages.map(&:id)
-    old_ids = viewport_message_ids
+    windowed = scope.select(
+      "messages.*",
+      "SUM(token_count) OVER (ORDER BY id DESC) AS running_total"
+    )
 
-    evicted = old_ids - new_ids
-    update_column(:viewport_message_ids, new_ids) if old_ids != new_ids
-    evicted
+    Message
+      .from(windowed, :messages)
+      .where("running_total <= ? OR running_total = token_count", token_budget)
+      .order(:id)
   end
 
-  # Overwrites the viewport snapshot without computing evictions.
-  # Used when transmitting or broadcasting a full viewport refresh,
-  # where eviction notifications are unnecessary (clients clear their
-  # store first).
+  # Returns the messages in the Mneme eviction zone — the oldest slice of
+  # the conversation starting from the boundary, filling the eviction budget
+  # walking newest-ward. These are the messages Mneme will summarize into a
+  # snapshot before advancing the boundary past them.
   #
-  # @param ids [Array<Integer>] message IDs now in the viewport
-  # @return [void]
-  def snapshot_viewport!(ids)
-    update_column(:viewport_message_ids, ids)
+  # Mirror of {#viewport_messages} but walks oldest-first from the boundary
+  # instead of newest-first from the tail.
+  #
+  # @return [ActiveRecord::Relation<Message>] chronologically ordered by id
+  def eviction_zone_messages
+    return Message.none unless mneme_boundary_message_id
+
+    budget = (Anima::Settings.token_budget * Anima::Settings.eviction_fraction).to_i
+
+    scope = messages.where("messages.id >= ?", mneme_boundary_message_id)
+
+    windowed = scope.select(
+      "messages.*",
+      "SUM(token_count) OVER (ORDER BY id ASC) AS running_total"
+    )
+
+    Message
+      .from(windowed, :messages)
+      .where("running_total <= ? OR running_total = token_count", budget)
+      .order(:id)
   end
 
-  # Returns skill names whose recalled content is currently visible in the
-  # viewport. Used by the analytical brain for deduplication — skills already
-  # in the viewport are excluded from the activation catalog.
+  # Names of skills currently present in the viewport as
+  # `from_melete_skill` phantom tool_call messages, in activation order.
   #
-  # @return [Set<String>] skill names present in the viewport
+  # @return [Array<String>] skill names in the viewport, activation order
   def skills_in_viewport
-    recalled_sources_in_viewport("skill")
+    from_melete_messages
+      .where("json_extract(payload, '$.tool_name') = ?", PendingMessage::MELETE_SKILL_TOOL)
+      .pluck(Arel.sql("json_extract(payload, '$.tool_input.skill')"))
+      .compact
   end
 
-  # Returns the workflow name currently visible in the viewport, if any.
-  # Only one workflow can be active at a time, so we return the first match.
+  # Workflow name currently present in the viewport as a
+  # `from_melete_workflow` phantom tool_call message, if any. The most
+  # recent activation wins when multiple are visible.
   #
-  # @return [String, nil] workflow name present in the viewport
+  # @return [String, nil] workflow name in the viewport, or nil
   def workflow_in_viewport
-    recalled_sources_in_viewport("workflow").first
+    from_melete_messages
+      .where("json_extract(payload, '$.tool_name') = ?", PendingMessage::MELETE_WORKFLOW_TOOL)
+      .reorder(id: :desc)
+      .pick(Arel.sql("json_extract(payload, '$.tool_input.workflow')"))
   end
 
-  # Returns the system prompt for this session.
-  # Sub-agent sessions use their stored prompt plus active skills and
-  # the pinned task. Main sessions assemble a full system prompt from
-  # soul and snapshots. Skills, workflows, and goals are injected as
-  # phantom tool_use/tool_result pairs in the message stream (not here)
-  # to keep the system prompt stable for prompt caching. Environment
-  # awareness flows through Bash tool responses.
+  # Active skills — skills Aoide is currently carrying or about to carry.
+  # Union of skills already promoted into the viewport and skills pending
+  # promotion. A skill is "active" from activation until eviction; there
+  # is no deactivation.
+  #
+  # @return [Array<String>] skill names, deduplicated, activation order first
+  def active_skills
+    queued = pending_messages.where(source_type: "skill").order(:id).pluck(:source_name)
+    (skills_in_viewport + queued).uniq
+  end
+
+  # Active workflow — the workflow Aoide is currently carrying or about
+  # to carry. Pending activations take precedence over viewport contents
+  # (the last enqueue wins; the previous phantom pair evicts naturally).
   #
-  # Sub-agent sessions still include expertise inline — they're short-lived
-  # and don't benefit from prompt caching.
+  # @return [String, nil]
+  def active_workflow
+    pending = pending_messages.where(source_type: "workflow").order(id: :desc).pick(:source_name)
+    pending || workflow_in_viewport
+  end
+
+  # Returns the system prompt for this session.
+  # Sub-agent sessions use their stored prompt plus the pinned task.
+  # Main sessions assemble a full system prompt from soul, sisters, and
+  # snapshots. Skills, workflows, and goals are injected as phantom
+  # tool_use/tool_result pairs in the message stream (not here) to keep
+  # the system prompt stable for prompt caching. Environment awareness
+  # flows through Bash tool responses.
   #
   # @return [String, nil] the system prompt text, or nil when nothing to inject
   def system_prompt
     if sub_agent?
-      [prompt, assemble_expertise_section, assemble_task_section].compact.join("\n\n")
+      [prompt, assemble_task_section].compact.join("\n\n")
     else
       assemble_system_prompt
     end
   end
 
-  # Activates a skill on this session. Validates the skill exists in the
-  # registry, updates active_skills, and enqueues the skill content as a
-  # {PendingMessage} so it enters the conversation as a phantom
-  # tool_use/tool_result pair through the normal promotion flow.
+  # Activates a skill on this session by enqueuing its content as a
+  # {PendingMessage} that promotes to a `from_melete_skill` phantom pair.
+  # Skips re-activation while the previous phantom pair is still in the
+  # viewport — Aoide already has the skill text in front of her.
   #
   # @param skill_name [String] name of the skill to activate
   # @return [Skills::Definition] the activated skill
   # @raise [Skills::InvalidDefinitionError] if skill not found in registry
-  # @raise [ActiveRecord::RecordInvalid] if save fails
   def activate_skill(skill_name)
     definition = Skills::Registry.instance.find(skill_name)
     raise Skills::InvalidDefinitionError, "Unknown skill: #{skill_name}" unless definition
-
     return definition if active_skills.include?(skill_name)
 
-    self.active_skills = active_skills + [skill_name]
-    save!
     enqueue_recall_message("skill", skill_name, definition.content)
+    Events::Bus.emit(Events::SkillActivated.new(session_id: id, skill_name: skill_name))
     definition
   end
 
-  # Deactivates a skill on this session. Removes it from active_skills and persists.
-  # The skill's recalled message stays in the conversation and evicts naturally.
-  #
-  # @param skill_name [String] name of the skill to deactivate
-  # @return [void]
-  def deactivate_skill(skill_name)
-    return unless active_skills.include?(skill_name)
-
-    self.active_skills = active_skills - [skill_name]
-    save!
-  end
-
-  # Activates a workflow on this session. Validates the workflow exists in the
-  # registry, sets it as the active workflow, and enqueues the workflow content
-  # as a {PendingMessage}. Only one workflow can be active at a time —
-  # activating a new one replaces the previous.
+  # Activates a workflow on this session by enqueuing its content as a
+  # {PendingMessage} that promotes to a `from_melete_workflow` phantom
+  # tool pair. Workflows are main-session only.
+  # Skips re-activation while the previous phantom pair is still in the
+  # viewport.
   #
   # @param workflow_name [String] name of the workflow to activate
   # @return [Workflows::Definition] the activated workflow
   # @raise [Workflows::InvalidDefinitionError] if workflow not found in registry
-  # @raise [ActiveRecord::RecordInvalid] if save fails
   def activate_workflow(workflow_name)
     definition = Workflows::Registry.instance.find(workflow_name)
     raise Workflows::InvalidDefinitionError, "Unknown workflow: #{workflow_name}" unless definition
-
     return definition if active_workflow == workflow_name
 
-    self.active_workflow = workflow_name
-    save!
     enqueue_recall_message("workflow", workflow_name, definition.content)
+    Events::Bus.emit(Events::WorkflowActivated.new(session_id: id, workflow_name: workflow_name))
     definition
   end
 
-  # Deactivates the current workflow on this session.
-  # The workflow's recalled message stays in the conversation and evicts naturally.
-  #
-  # @return [void]
-  def deactivate_workflow
-    return unless active_workflow.present?
-
-    self.active_workflow = nil
-    save!
-  end
-
-  # Assembles the system prompt: version preamble, soul, and snapshots.
-  # Skills, workflows, goals, and environment awareness flow through the
-  # message stream and tool responses, keeping the system prompt stable
-  # for prompt caching.
+  # Assembles the system prompt: version preamble, soul, sisters block,
+  # available tools menu, tool guidelines, and snapshots. Skills,
+  # workflows, goals, and environment awareness flow through the message
+  # stream and tool responses, keeping the system prompt stable for
+  # prompt caching.
   #
   # @return [String] composed system prompt
   def assemble_system_prompt
-    [assemble_version_preamble, assemble_soul_section, assemble_snapshots_section]
-      .compact.join("\n\n")
+    [
+      assemble_version_preamble,
+      assemble_soul_section,
+      assemble_sisters_section,
+      assemble_available_tools_section,
+      assemble_tool_guidelines_section,
+      assemble_snapshots_section
+    ].compact.join("\n\n")
   end
 
   # Serializes non-evicted goals as a lightweight summary for ActionCable
@@ -293,7 +337,7 @@ class Session < ApplicationRecord
     pinned_budget = (token_budget * Anima::Settings.mneme_pinned_budget_fraction).to_i
     sliding_budget -= pinned_budget
 
-    window = viewport_messages(token_budget: sliding_budget)
+    window = viewport_messages(token_budget: sliding_budget).to_a
     first_message_id = window.first&.id
 
     prefix = assemble_context_prefix_messages(first_message_id, budget: pinned_budget)
@@ -342,72 +386,72 @@ class Session < ApplicationRecord
     healed
   end
 
-  # Delivers a user message respecting the session's processing state.
-  #
-  # When idle, persists the message directly and enqueues {AgentRequestJob}
-  # to process it. When mid-turn ({#processing?}), stages the message as
-  # a {PendingMessage} in a separate table — it gets no message ID until
-  # promoted, so it can never interleave with tool_call/tool_response pairs.
+  # Enqueues an inbound human-side message (direct user input or a
+  # sub-agent reply) as an active {PendingMessage}. The PM's
+  # +after_create_commit+ emits the appropriate pipeline event when the
+  # session is idle (+StartMelete+ for user input, +StartProcessing+ for
+  # sub-agent deliveries). On a busy session the PM queues silently and
+  # {#wake_drain_pipeline_if_pending} picks it up on the next transition
+  # into +:idle+.
   #
   # @param content [String] message text (raw, without attribution)
   # @param source_type [String] origin type: "user" (default) or "subagent"
   # @param source_name [String, nil] sub-agent nickname (required when source_type is "subagent")
-  # @param bounce_back [Boolean] when true, passes +message_id+ to the job
-  #   so failed LLM delivery triggers a {Events::BounceBack} (used by
-  #   {SessionChannel#speak} for immediate-display messages)
-  # @return [void]
+  # @param bounce_back [Boolean] when true, a failed first LLM call on the
+  #   promoted message triggers a {Events::BounceBack} so the TUI can
+  #   restore the text to the input field
+  # @return [PendingMessage]
   def enqueue_user_message(content, source_type: "user", source_name: nil, bounce_back: false)
-    if processing?
-      pending_messages.create!(content: content, source_type: source_type, source_name: source_name)
-    else
-      display = if source_type == "subagent"
-        format(Tools::ResponseTruncator::ATTRIBUTION_FORMAT, source_name, content)
-      else
-        content
-      end
-      msg = create_user_message(display)
-      job_args = bounce_back ? {message_id: msg.id} : {}
-      AgentRequestJob.perform_later(id, **job_args)
-    end
+    message_type = (source_type == "subagent") ? "subagent" : "user_message"
+    pending_messages.create!(
+      content: content,
+      source_type: source_type,
+      source_name: source_name,
+      message_type: message_type,
+      bounce_back: bounce_back
+    )
   end
 
-  # Promotes a phantom pair pending message into a tool_call/tool_response pair.
-  # These persist as real Message records and ride the conveyor belt.
-  #
-  # @param pm [PendingMessage] phantom pair pending message
+  # Promotes a phantom-pair PendingMessage into a synthetic
+  # tool_call/tool_response Message pair — the LLM sees "a tool I
+  # invoked returned a result" and the pair rides the viewport like
+  # any real tool round. Used by {DrainJob} to flush background
+  # enrichment PMs (recalled memories, activated skills, workflow
+  # triggers, goal events, sub-agent deliveries) into the
+  # conversation.
+  #
+  # Releases a failed drain claim and bounces the promoted user-message
+  # back to the client. Called from {DrainJob} when the LLM call raises
+  # before {Events::LLMResponded} ships. Destroying the exact message the
+  # PM promoted (tracked in {PendingMessage#promoted_message_id}) avoids
+  # the "last user_message" guess, which was racy under parallel drains.
+  #
+  # Idempotent — a nil +promoted_message_id+ skips the destroy and emits
+  # the BounceBack with +message_id: nil+ so the TUI still restores input.
+  #
+  # @param pm [PendingMessage] the user-message PM that failed to round-trip
+  # @param error [Exception] the raised error
   # @return [void]
-  def promote_phantom_pair!(pm)
-    tool_name = pm.phantom_tool_name
-    tool_input = pm.phantom_tool_input
-    uid = "#{tool_name}_#{pm.id}"
-    now = now_ns
-
-    messages.create!(
-      message_type: "tool_call",
-      tool_use_id: uid,
-      payload: {"tool_name" => tool_name, "tool_use_id" => uid,
-                "tool_input" => tool_input.stringify_keys,
-                "content" => pm.display_content.lines.first.chomp},
-      timestamp: now,
-      token_count: Mneme::PassiveRecall::TOOL_PAIR_OVERHEAD_TOKENS
-    )
-
-    messages.create!(
-      message_type: "tool_response",
-      tool_use_id: uid,
-      payload: {"tool_name" => tool_name, "tool_use_id" => uid,
-                "content" => pm.content, "success" => true},
-      timestamp: now,
-      token_count: Message.estimate_token_count(pm.content.bytesize)
-    )
+  def release_with_bounce_back(pm, error)
+    response_complete! if may_response_complete?
+
+    bounced = pm.promoted_message_id && messages.find_by(id: pm.promoted_message_id)
+    bounced&.destroy!
+
+    Events::Bus.emit(Events::BounceBack.new(
+      content: pm.content,
+      error: error.message,
+      session_id: id,
+      message_id: bounced&.id
+    ))
   end
 
-  # Persists a user message directly, bypassing the pending queue.
-  #
-  # Used by {#enqueue_user_message} (idle path), {AgentLoop#run},
-  # and sub-agent spawn tools ({Tools::SpawnSubagent}, {Tools::SpawnSpecialist})
-  # because the global {Events::Subscribers::Persister} skips non-pending user
-  # messages — these callers own the persistence lifecycle.
+  # Persists a user_message Message directly — skipping the PendingMessage
+  # mailbox. Used by {DrainJob} to finalize a promoted user_message PM
+  # and by the sub-agent spawn tools ({Tools::SpawnSubagent},
+  # {Tools::SpawnSpecialist}) to seed the child's conversation with its
+  # assigned task. The global {Events::Subscribers::Persister} skips
+  # +user_message+ events, so these callers own the persistence.
   #
   # @param content [String] user message text
   # @param source_type [String, nil] origin type (e.g. "skill", "workflow")
@@ -426,43 +470,11 @@ class Session < ApplicationRecord
     )
   end
 
-  # Promotes all pending messages into the conversation history.
-  # Each {PendingMessage} is atomically deleted and replaced with a real
-  # {Message} — the new message gets the next auto-increment ID,
-  # naturally placing it after any tool_call/tool_response pairs that
-  # were persisted while the message was waiting.
-  #
-  # Returns a hash with two keys:
-  # - +:texts+ — plain content strings for user messages (injected as text blocks
-  #   within the current tool_results turn)
-  # - +:pairs+ — synthetic tool_use/tool_result message hashes for phantom pair
-  #   types (appended as new conversation turns)
-  #
-  # @return [Hash{Symbol => Array}] promoted messages split by injection strategy
-  def promote_pending_messages!
-    texts = []
-    pairs = []
-    pending_messages.find_each do |pm|
-      transaction do
-        if pm.phantom_pair?
-          promote_phantom_pair!(pm)
-        else
-          create_user_message(pm.display_content, source_type: pm.source_type, source_name: pm.source_name)
-        end
-        pm.destroy!
-      end
-      if pm.phantom_pair?
-        pairs.concat(pm.to_llm_messages)
-      else
-        texts << pm.content
-      end
-    end
-    {texts: texts, pairs: pairs}
-  end
-
   # Broadcasts child session list to all clients subscribed to the parent
-  # session. Called when a child session is created or its processing state
-  # changes so the HUD sub-agents section updates in real time.
+  # session. Called when a child session is created or its AASM state
+  # changes so the HUD sub-agents section updates in real time. Evicted
+  # sub-agents (+hud_visible: false+) are filtered out — the panel mirrors
+  # what Aoide currently carries in her viewport.
   #
   # Queries children via FK directly (avoids loading the parent record) and
   # selects only the columns needed for the HUD payload.
@@ -471,44 +483,111 @@ class Session < ApplicationRecord
   def broadcast_children_update_to_parent
     return unless parent_session_id
 
-    children = Session.where(parent_session_id: parent_session_id)
+    children = Session.where(parent_session_id: parent_session_id, hud_visible: true)
       .order(:created_at)
-      .select(:id, :name, :processing)
+      .select(:id, :name, :aasm_state)
     ActionCable.server.broadcast("session_#{parent_session_id}", {
       "action" => "children_updated",
       "session_id" => parent_session_id,
       "children" => children.map { |child|
-        state = child.processing? ? "llm_generating" : "idle"
-        {"id" => child.id, "name" => child.name, "processing" => child.processing?, "session_state" => state}
+        {"id" => child.id, "name" => child.name, "session_state" => child.aasm_state}
       }
     })
   end
 
-  # Broadcasts the session's current processing state to all subscribed
-  # clients. Stateless — no storage, pure broadcast. The TUI uses this to
-  # drive the braille spinner animation and sub-agent HUD icons.
-  #
-  # Payload broadcast to +session_{id}+:
-  #   {"action" => "session_state", "state" => state, "session_id" => id}
-  #   # plus "tool" key when state is "tool_executing"
+  # True when at least one of +child+'s traces (the +spawn_subagent+ tool
+  # pair or any +from_{nickname}+ phantom pair) still lives above the
+  # Mneme boundary in this session's viewport. Used by {Mneme::Runner}
+  # after boundary advancement to decide whether a child should drop out
+  # of the HUD panel.
+  #
+  # Returns +false+ when the given session isn't a direct child, when it
+  # has no +spawn_tool_use_id+ (legacy child), or when the boundary has
+  # passed every trace.
+  #
+  # @param child [Session] a sub-agent session to check
+  # @return [Boolean]
+  def subagent_trace_in_viewport?(child)
+    return false unless child.parent_session_id == id
+
+    boundary_id = mneme_boundary_message_id
+    scope = messages
+    scope = scope.where("messages.id >= ?", boundary_id) if boundary_id
+
+    spawn_uid = child.spawn_tool_use_id
+    nickname = child.name
+    conditions = []
+    bindings = {}
+    if spawn_uid
+      conditions << "messages.tool_use_id = :uid"
+      bindings[:uid] = spawn_uid
+    end
+    if nickname
+      conditions << "json_extract(messages.payload, '$.tool_name') = :tool"
+      bindings[:tool] = "from_#{nickname}"
+    end
+    return false if conditions.empty?
+
+    scope.where(conditions.join(" OR "), **bindings).exists?
+  end
+
+  # AASM guard for the +executing → awaiting+ branch of +start_processing+.
+  # The round is complete when every orphan +tool_call+ Message (one
+  # without a matching +tool_response+ Message) has a corresponding
+  # +tool_response+ PendingMessage waiting to be promoted. Until then the
+  # drain bails so the LLM never sees a half-assembled tool turn.
+  #
+  # @return [Boolean]
+  def tool_round_complete?
+    msg_responses = messages.where(message_type: "tool_response").select(:tool_use_id)
+    pm_responses = pending_messages.where(message_type: "tool_response").select(:tool_use_id)
+    messages.where(message_type: "tool_call")
+      .where.not(tool_use_id: msg_responses)
+      .where.not(tool_use_id: pm_responses)
+      .none?
+  end
+
+  # AASM after_all_events callback — publishes
+  # {Events::SessionStateChanged} so the broadcaster subscriber can keep
+  # the TUI spinner and parent-session HUD in sync with the state machine.
+  # Fires after the state column is updated and persisted, so +aasm_state+
+  # reliably holds the post-transition value.
   #
-  # For sub-agents, also broadcasts +child_state+ to the parent stream:
-  #   {"action" => "child_state", "state" => state, "session_id" => id, "child_id" => id}
+  # @return [void]
+  def emit_state_change
+    Events::Bus.emit(Events::SessionStateChanged.new(session_id: id, state: aasm_state))
+  end
+
+  # AASM after_all_events callback — clears the +interrupt_requested+
+  # flag whenever the session lands in +:idle+. The flag is a
+  # one-shot signal that long-running tools ({Tools::Bash}) poll; once
+  # the round ends (tool aborted, response synthesized, drain wound
+  # down) the signal is spent and must not leak into the next round.
   #
-  # @param state [String] one of "idle", "llm_generating", "tool_executing", "interrupting"
-  # @param tool [String, nil] tool name when state is "tool_executing"
   # @return [void]
-  def broadcast_session_state(state, tool: nil)
-    payload = {"action" => "session_state", "state" => state, "session_id" => id}
-    payload["tool"] = tool if tool
-    ActionCable.server.broadcast("session_#{id}", payload)
+  def clear_interrupt_flag_if_idle
+    return unless idle?
+    return unless interrupt_requested?
 
-    # Notify the parent's stream so the HUD updates child state icons
-    # without requiring a full children_updated query.
-    return unless parent_session_id
+    update_column(:interrupt_requested, false)
+  end
+
+  # AASM after_all_events callback — picks the oldest active
+  # PendingMessage and re-runs its pipeline routing whenever the session
+  # lands in +:idle+ with work still queued. Covers the race where a PM
+  # arrives while the session is +:awaiting+ (LLM in flight): its own
+  # +after_create_commit+ saw +may_start_processing?+ return false and
+  # emitted nothing, so without this callback the message would sit
+  # forever once the LLM call completed.
+  #
+  # The +:executing → :awaiting+ path (tool round close) does not need
+  # this callback — the closing tool_response PM is itself the wake.
+  #
+  # @return [void]
+  def wake_drain_pipeline_if_pending
+    return unless idle?
 
-    parent_payload = payload.merge("action" => "child_state", "child_id" => id)
-    ActionCable.server.broadcast("session_#{parent_session_id}", parent_payload)
+    pending_messages.ordered_for_drain.first&.route_to_event_bus
   end
 
   # Broadcasts the full LLM debug context to debug-mode TUI clients.
@@ -524,6 +603,25 @@ class Session < ApplicationRecord
     ActionCable.server.broadcast("session_#{id}", self.class.system_prompt_payload(system, tools: tools))
   end
 
+  # Broadcasts current active skills and workflow to all subscribers.
+  # "Active" is viewport-derived — the HUD reflects what Aoide actually
+  # has in front of her. Callers invoke this after any operation that
+  # changes viewport composition (phantom pair promotion, Mneme eviction).
+  #
+  # @return [void]
+  def broadcast_active_state!
+    ActionCable.server.broadcast("session_#{id}", {
+      "action" => "active_skills_updated",
+      "session_id" => id,
+      "active_skills" => active_skills
+    })
+    ActionCable.server.broadcast("session_#{id}", {
+      "action" => "active_workflow_updated",
+      "session_id" => id,
+      "active_workflow" => active_workflow
+    })
+  end
+
   # Returns the deterministic tool schemas for this session's type and
   # granted_tools configuration. Standard and spawn tools are static
   # class-level definitions — no ShellSession or registry needed.
@@ -532,22 +630,7 @@ class Session < ApplicationRecord
   #
   # @return [Array<Hash>] tool schema hashes matching Anthropic tools API format
   def tool_schemas
-    tools = if granted_tools
-      granted = granted_tools.filter_map { |name| AgentLoop::STANDARD_TOOLS_BY_NAME[name] }
-      (AgentLoop::ALWAYS_GRANTED_TOOLS + granted).uniq
-    else
-      AgentLoop::STANDARD_TOOLS.dup
-    end
-
-    unless sub_agent?
-      tools.push(Tools::SpawnSubagent, Tools::SpawnSpecialist, Tools::OpenIssue)
-    end
-
-    if sub_agent?
-      tools.push(Tools::MarkGoalCompleted)
-    end
-
-    tools.map(&:schema)
+    resolved_tool_classes.map(&:schema)
   end
 
   # Builds the system prompt payload for debug mode transmission.
@@ -559,9 +642,8 @@ class Session < ApplicationRecord
   # @param tools [Array<Hash>, nil] tool schemas
   # @return [Hash] payload with type, rendered debug content, and token estimate
   def self.system_prompt_payload(prompt, tools: nil)
-    total_bytes = prompt.bytesize
-    total_bytes += tools.to_json.bytesize if tools&.any?
-    tokens = Message.estimate_token_count(total_bytes)
+    tools_json = tools&.any? ? tools.to_json : ""
+    tokens = TokenEstimation.estimate_token_count(prompt.to_s + tools_json)
 
     debug = {role: :system_prompt, content: prompt, tokens: tokens, estimated: true}
     debug[:tools] = tools if tools&.any?
@@ -575,33 +657,40 @@ class Session < ApplicationRecord
 
   private
 
-  # Finds recalled skill/workflow source names in the current viewport.
-  # Scans viewport messages for user_messages tagged with the given source_type.
-  #
-  # @param source_type [String] "skill" or "workflow"
-  # @return [Set<String>] source names present in the viewport
-  def recalled_sources_in_viewport(source_type)
-    ids = viewport_message_ids
-    return Set.new if ids.empty?
-
-    messages
-      .where(id: ids, message_type: "user_message")
-      .where("json_extract(payload, '$.source_type') = ?", source_type)
-      .pluck(Arel.sql("json_extract(payload, '$.source_name')"))
-      .to_set
+  # Returns `from_melete_*` tool_call messages currently in the viewport
+  # as a composable AR relation. Used by {#skills_in_viewport} and
+  # {#workflow_in_viewport} to derive active state with additional
+  # `.where` clauses on the tool name suffix.
+  #
+  # @return [ActiveRecord::Relation<Message>] chronologically ordered
+  def from_melete_messages
+    viewport_messages
+      .where(message_type: "tool_call")
+      .where("json_extract(payload, '$.tool_name') GLOB ?", "from_melete_*")
+      .order(:id)
   end
 
-  # Enqueues a recalled skill or workflow as a {PendingMessage}.
-  # Always goes through the pending queue because the analytical brain
-  # only runs during processing. The message enters the conversation
-  # through the normal promotion flow as a phantom tool_use/tool_result pair.
+  # Enqueues a Melete-recalled skill or workflow as a background
+  # {PendingMessage}. {DrainJob} flushes it into the conversation as a
+  # phantom tool_use/tool_result pair on the next drain cycle.
   #
   # @param source_type [String] "skill" or "workflow"
   # @param source_name [String] skill or workflow name
   # @param content [String] definition content to recall
   # @return [PendingMessage] the created pending message
   def enqueue_recall_message(source_type, source_name, content)
-    pending_messages.create!(content: content, source_type: source_type, source_name: source_name)
+    message_type = case source_type
+    when "skill" then "from_melete_skill"
+    when "workflow" then "from_melete_workflow"
+    else raise ArgumentError, "unknown recall source_type: #{source_type.inspect}"
+    end
+
+    pending_messages.create!(
+      content: content,
+      source_type: source_type,
+      source_name: source_name,
+      message_type: message_type
+    )
   end
 
   # One-line version preamble so the agent knows its own version.
@@ -627,25 +716,64 @@ class Session < ApplicationRecord
     File.read(path).strip
   end
 
-  # Assembles the expertise section of the system prompt from active skills
-  # and the active workflow. Both are injected into the same "Your Expertise"
-  # section — the main agent treats them identically as domain knowledge.
+  # Introduces Melete and Mneme so the agent recognizes their
+  # contributions as delivered-to-her rather than self-invoked. The
+  # `from_` prefix carries the semantics — the section just makes the
+  # convention explicit once.
   #
-  # @return [String, nil] expertise section, or nil when nothing is active
-  def assemble_expertise_section
-    sections = active_skills.filter_map do |skill_name|
-      definition = Skills::Registry.instance.find(skill_name)
-      format_expertise_section(definition, skill_name)
-    end
+  # @return [String] sisters section
+  def assemble_sisters_section
+    <<~SISTERS.strip
+      ## Your Sisters
+
+      You don't work alone. Two muses share the conversation with you, and their work arrives as tool responses prefixed `from_`:
 
-    if active_workflow.present?
-      definition = Workflows::Registry.instance.find(active_workflow)
-      sections << format_expertise_section(definition, active_workflow) if definition
+      - **Melete**, the muse of practice, prepares the stage before you speak. Her contributions arrive as `from_melete_skill`, `from_melete_workflow`, and `from_melete_goal`.
+      - **Mneme**, the muse of memory, holds what has slipped past your immediate attention. When something from earlier matters again she surfaces it as `from_mneme`.
+
+      Sub-agents you spawn arrive the same way, named after whoever sent them — `from_sleuth`, `from_scout`, and so on.
+
+      **How delivery works:** Results from sisters and sub-agents appear automatically as tool responses in your conversation — you don't fetch them. There is no tool to call, no way to poll, and no status to check. When a sub-agent finishes, its output shows up on its own. If you're waiting on multiple agents, just wait — they'll arrive. Do other work in the meantime if you can.
+    SISTERS
+  end
+
+  # Renders a one-line menu of the session's available tools, populated
+  # from each tool's {Tools::Base.prompt_snippet}. Tools without a snippet
+  # are omitted; the section disappears entirely when no tool contributes.
+  #
+  # @return [String, nil] available tools section, or nil when empty
+  def assemble_available_tools_section
+    menu = resolved_tool_classes.filter_map do |tool|
+      snippet = tool.prompt_snippet
+      "- #{tool.tool_name}: #{snippet}" if snippet
     end
+    return if menu.empty?
 
-    return if sections.empty?
+    "## Available Tools\n\n#{menu.join("\n")}"
+  end
 
-    "## Your Expertise\n\nYou know this deeply. Now's your chance to put it to work.\n\n#{sections.join("\n\n")}"
+  # Concatenates each available tool's {Tools::Base.prompt_guidelines}
+  # into a single behavioral guidance section. Guidelines steer cross-tool
+  # selection (e.g. prefer edit_file over `sed`) and reinforce non-obvious
+  # behaviour the schema cannot convey at every reasoning token.
+  #
+  # @return [String, nil] tool guidelines section, or nil when empty
+  def assemble_tool_guidelines_section
+    bullets = resolved_tool_classes.flat_map(&:prompt_guidelines).map { |line| "- #{line}" }
+    return if bullets.empty?
+
+    "## Tool Guidelines\n\n#{bullets.join("\n")}"
+  end
+
+  # Memoizes the active tool classes for this session by delegating to
+  # {Tools::Registry.tool_classes_for} — the shared resolver used by
+  # {.build}, {#tool_schemas}, and the prompt section assemblers so all
+  # views stay in sync. Safe to memoize: +granted_tools+ and +sub_agent?+
+  # are immutable post-creation.
+  #
+  # @return [Array<Class>] tool classes (no MCP tools — those are dynamic)
+  def resolved_tool_classes
+    @resolved_tool_classes ||= Tools::Registry.tool_classes_for(self)
   end
 
   # Assembles the task section for sub-agent system prompts.
@@ -685,22 +813,6 @@ class Session < ApplicationRecord
     lines.join("\n")
   end
 
-  # Formats a definition (skill or workflow) as a Markdown section for the
-  # expertise prompt. Extracts the first Markdown heading from content for
-  # the section title; falls back to the definition name when content has
-  # no heading.
-  #
-  # @param definition [Skills::Definition, Workflows::Definition, nil] the definition to format
-  # @param fallback_name [String] name to use if content has no heading
-  # @return [String, nil] formatted section, or nil if definition is nil
-  def format_expertise_section(definition, fallback_name)
-    return unless definition
-
-    content = definition.content
-    heading = content.lines.first&.sub(/^#+ /, "")&.strip || fallback_name
-    "### #{heading}\n\n#{content}"
-  end
-
   # Broadcasts a name change to all clients subscribed to this session.
   # Triggered by after_update_commit so clients see name updates in real time.
   #
@@ -713,66 +825,6 @@ class Session < ApplicationRecord
     })
   end
 
-  # Broadcasts active skill changes to all clients subscribed to this session.
-  # Triggered by after_update_commit so the TUI info panel updates reactively.
-  #
-  # @return [void]
-  def broadcast_active_skills_update
-    ActionCable.server.broadcast("session_#{id}", {
-      "action" => "active_skills_updated",
-      "session_id" => id,
-      "active_skills" => active_skills
-    })
-  end
-
-  # Broadcasts active workflow change to all clients subscribed to this session.
-  # Triggered by after_update_commit so the TUI info panel updates reactively.
-  #
-  # @return [void]
-  def broadcast_active_workflow_update
-    ActionCable.server.broadcast("session_#{id}", {
-      "action" => "active_workflow_updated",
-      "session_id" => id,
-      "active_workflow" => active_workflow
-    })
-  end
-
-  # Scopes own messages for viewport assembly.
-  # Starts from the Mneme boundary (inclusive) — older messages have been
-  # compressed into snapshots and no longer participate in the viewport.
-  # @return [ActiveRecord::Relation]
-  def own_message_scope
-    scope = messages.context_messages
-    scope = scope.where("messages.id >= ?", mneme_boundary_message_id) if mneme_boundary_message_id
-    scope
-  end
-
-  # Walks messages newest-first, selecting until the token budget is exhausted.
-  # Always includes at least the newest message even if it exceeds budget.
-  #
-  # @param scope [ActiveRecord::Relation] message scope to select from
-  # @param budget [Integer] maximum tokens to include
-  # @return [Array<Message>] chronologically ordered
-  def select_messages(scope, budget:)
-    selected = []
-    remaining = budget
-
-    scope.reorder(id: :desc).each do |msg|
-      cost = message_token_cost(msg)
-      break if cost > remaining && selected.any?
-
-      selected << msg
-      remaining -= cost
-    end
-
-    selected.reverse
-  end
-
-  # @return [Integer] token cost, using cached count or heuristic estimate
-  def message_token_cost(msg)
-    (msg.token_count > 0) ? msg.token_count : estimate_tokens(msg)
-  end
-
   # Ensures every tool_call in the message list has a matching tool_response
   # (and vice versa) by removing unpaired messages. The Anthropic API requires
   # every tool_use block to have a tool_result — a missing partner causes
@@ -800,25 +852,20 @@ class Session < ApplicationRecord
   end
 
   # Assembles L1/L2 snapshots as a system prompt section.
-  # Snapshots are visible when their source messages precede the Mneme boundary
-  # (compressed in a previous run). Between Mneme runs this section is frozen,
-  # making it cache-friendly.
+  # Snapshots form a compressed timeline between the system prompt and
+  # the live viewport. The budget walk fills chronologically — when the
+  # budget overflows, the oldest snapshots drop first so the most recent
+  # ones always bridge into the viewport.
   #
   # @return [String, nil] formatted snapshot text for the system prompt, or nil
   def assemble_snapshots_section
-    reference_id = mneme_boundary_message_id || viewport_message_ids.first
-    return unless reference_id
-
-    l2_budget = (Anima::Settings.token_budget * Anima::Settings.mneme_l2_budget_fraction).to_i
-    l1_budget = (Anima::Settings.token_budget * Anima::Settings.mneme_l1_budget_fraction).to_i
-
     l2 = select_snapshots_within_budget(
-      snapshots.for_level(2).source_messages_evicted(reference_id).chronological,
-      budget: l2_budget
+      snapshots.for_level(2),
+      budget: (Anima::Settings.token_budget * Anima::Settings.mneme_l2_budget_fraction).to_i
     )
     l1 = select_snapshots_within_budget(
-      snapshots.for_level(1).not_covered_by_l2.source_messages_evicted(reference_id).chronological,
-      budget: l1_budget
+      snapshots.for_level(1).not_covered_by_l2,
+      budget: (Anima::Settings.token_budget * Anima::Settings.mneme_l1_budget_fraction).to_i
     )
 
     sections = []
@@ -827,9 +874,10 @@ class Session < ApplicationRecord
     sections.join("\n\n").presence
   end
 
-  # Walks snapshots chronologically, selecting until the token budget is exhausted.
-  # Always includes at least one snapshot even if it exceeds the budget, so the
-  # agent never loses all memory context.
+  # Walks snapshots newest-first (by to_message_id), selecting until the
+  # token budget is exhausted. Always includes the newest snapshot even
+  # if it exceeds the budget. Returns results in chronological order
+  # so they read as a timeline in the system prompt.
   #
   # @param scope [ActiveRecord::Relation] snapshot scope to select from
   # @param budget [Integer] maximum tokens to include
@@ -838,15 +886,15 @@ class Session < ApplicationRecord
     selected = []
     remaining = budget
 
-    scope.each do |snapshot|
-      cost = snapshot.token_cost
+    scope.order(to_message_id: :desc).each do |snapshot|
+      cost = snapshot.token_count
       break if cost > remaining && selected.any?
 
       selected << snapshot
       remaining -= cost
     end
 
-    selected
+    selected.reverse
   end
 
   # Formats a list of snapshots as a labeled section for the system prompt.
@@ -877,12 +925,9 @@ class Session < ApplicationRecord
     root_goals = goals.root.active.includes(:sub_goals).order(:created_at)
     return [] if root_goals.empty?
 
-    pins = pinned_messages
+    pins_scope = pinned_messages.where("pinned_messages.message_id < ?", first_message_id)
+    selected_pins = select_pins_within_budget(pins_scope, budget: budget)
       .includes(:message, :goals)
-      .where("pinned_messages.message_id < ?", first_message_id)
-      .order("pinned_messages.message_id")
-
-    selected_pins = select_pins_within_budget(pins, budget)
     content = render_goal_snapshot_with_pins(root_goals, selected_pins)
 
     # Uses session ID (not PendingMessage ID) because this snapshot is
@@ -890,7 +935,7 @@ class Session < ApplicationRecord
     uid = "goal_snapshot_#{id}"
     [
       {role: "assistant", content: [
-        {type: "tool_use", id: uid, name: PendingMessage::RECALL_GOAL_TOOL, input: {}}
+        {type: "tool_use", id: uid, name: PendingMessage::MELETE_GOAL_TOOL, input: {}}
       ]},
       {role: "user", content: [
         {type: "tool_result", tool_use_id: uid, content: content}
@@ -898,25 +943,25 @@ class Session < ApplicationRecord
     ]
   end
 
-  # Walks pinned messages chronologically, selecting until the token budget
-  # is exhausted. Always includes at least one pin.
+  # Selects pins within a token budget using a cumulative-sum window
+  # function — mirror of {#eviction_zone_messages} but keyed by
+  # +message_id+. Walks oldest-first and always anchors on the first
+  # pin even if it alone exceeds the budget (via
+  # +running_total = token_count+).
   #
-  # @param pins [Array<PinnedMessage>]
-  # @param budget [Integer]
-  # @return [Array<PinnedMessage>]
-  def select_pins_within_budget(pins, budget)
-    selected = []
-    remaining = budget
-
-    pins.each do |pin|
-      cost = pin.token_cost
-      break if cost > remaining && selected.any?
-
-      selected << pin
-      remaining -= cost
-    end
+  # @param scope [ActiveRecord::Relation] pin scope to select from
+  # @param budget [Integer] maximum tokens to include
+  # @return [ActiveRecord::Relation<PinnedMessage>] chronologically ordered
+  def select_pins_within_budget(scope, budget:)
+    windowed = scope.select(
+      "pinned_messages.*",
+      "SUM(pinned_messages.token_count) OVER (ORDER BY pinned_messages.message_id ASC) AS running_total"
+    )
 
-    selected
+    PinnedMessage
+      .from(windowed, :pinned_messages)
+      .where("running_total <= ? OR running_total = token_count", budget)
+      .order(:message_id)
   end
 
   # Renders active goals with their associated pinned messages as a
@@ -1104,13 +1149,4 @@ class Session < ApplicationRecord
   def now_ns
     Time.current.to_ns
   end
-
-  # Delegates to {Message#estimate_tokens} for messages not yet counted
-  # by the background job.
-  #
-  # @param msg [Message]
-  # @return [Integer] at least 1
-  def estimate_tokens(msg)
-    msg.estimate_tokens
-  end
 end