anima-core 1.1.3 → 1.3.0

data/app/models/snapshot.rb

@@ -1,22 +1,22 @@
 # frozen_string_literal: true
 
 # A persisted summary of conversation context created by Mneme before
-# events evict from the viewport. Snapshots capture the "gist" of what
+# messages evict from the viewport. Snapshots capture the "gist" of what
 # happened so the agent retains awareness of past context.
 #
-# Level 1 snapshots are created from raw events (messages + thinks).
+# Level 1 snapshots are created from raw messages (conversation + thinks).
 # Level 2 snapshots compress multiple Level 1 snapshots (days/weeks scale).
-# Both levels use the same event ID range tracking — an L2 snapshot's range
+# Both levels use the same message ID range tracking — an L2 snapshot's range
 # is the union of its constituent L1 snapshots.
 #
 # @!attribute text
 #   @return [String] the summary text generated by Mneme
-# @!attribute from_event_id
-#   @return [Integer] first event ID covered by this snapshot
-# @!attribute to_event_id
-#   @return [Integer] last event ID covered by this snapshot
+# @!attribute from_message_id
+#   @return [Integer] first message ID covered by this snapshot
+# @!attribute to_message_id
+#   @return [Integer] last message ID covered by this snapshot
 # @!attribute level
-#   @return [Integer] compression level (1 = from raw events, 2 = from L1 snapshots)
+#   @return [Integer] compression level (1 = from raw messages, 2 = from L1 snapshots)
 # @!attribute token_count
 #   @return [Integer] cached token count of the summary text
 class Snapshot < ApplicationRecord
@@ -27,34 +27,34 @@ class Snapshot < ApplicationRecord
   MAX_TEXT_BYTES = 32_768
 
   validates :text, presence: true, length: {maximum: MAX_TEXT_BYTES}
-  validates :from_event_id, presence: true
-  validates :to_event_id, presence: true
+  validates :from_message_id, presence: true
+  validates :to_message_id, presence: true
   validates :level, presence: true, numericality: {greater_than: 0}
   validates :token_count, numericality: {greater_than_or_equal_to: 0}, allow_nil: true
-  validate :from_event_id_not_after_to_event_id
+  validate :from_message_id_not_after_to_message_id
 
   scope :for_level, ->(level) { where(level: level) }
-  scope :chronological, -> { order(:from_event_id) }
+  scope :chronological, -> { order(:from_message_id) }
 
-  # L1 snapshots whose event range is NOT fully contained within any L2 snapshot.
+  # L1 snapshots whose message range is NOT fully contained within any L2 snapshot.
   # Used to determine which L1 snapshots are still "live" in the viewport.
   scope :not_covered_by_l2, -> {
     where.not(
       "EXISTS (SELECT 1 FROM snapshots l2 " \
       "WHERE l2.session_id = snapshots.session_id " \
       "AND l2.level = 2 " \
-      "AND l2.from_event_id <= snapshots.from_event_id " \
-      "AND l2.to_event_id >= snapshots.to_event_id)"
+      "AND l2.from_message_id <= snapshots.from_message_id " \
+      "AND l2.to_message_id >= snapshots.to_message_id)"
     )
   }
 
-  # Snapshots whose source events have fully evicted from the sliding window.
-  # A snapshot is visible when its entire event range precedes the first
-  # event currently in the viewport.
+  # Snapshots whose source messages have fully evicted from the sliding window.
+  # A snapshot is visible when its entire message range precedes the first
+  # message currently in the viewport.
   #
-  # @param first_event_id [Integer] the first event ID in the sliding window
-  scope :source_events_evicted, ->(first_event_id) {
-    where("to_event_id < ?", first_event_id)
+  # @param first_message_id [Integer] the first message ID in the sliding window
+  scope :source_messages_evicted, ->(first_message_id) {
+    where("to_message_id < ?", first_message_id)
   }
 
   # @return [Integer] token cost, using cached count or heuristic estimate
@@ -64,13 +64,13 @@ class Snapshot < ApplicationRecord
 
   private
 
-  def from_event_id_not_after_to_event_id
-    return unless from_event_id && to_event_id
-    errors.add(:from_event_id, "must be <= to_event_id") if from_event_id > to_event_id
+  def from_message_id_not_after_to_message_id
+    return unless from_message_id && to_message_id
+    errors.add(:from_message_id, "must be <= to_message_id") if from_message_id > to_message_id
   end
 
   # @return [Integer] estimated token count (at least 1)
   def estimate_tokens
-    [(text.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
+    [(text.bytesize / Message::BYTES_PER_TOKEN.to_f).ceil, 1].max
   end
 end

data/config/environments/test.rb

@@ -6,4 +6,9 @@ Rails.application.configure do
   config.consider_all_requests_local = true
   config.active_support.deprecation = :stderr
   config.active_job.queue_adapter = :test
+
+  # Fixed keys for test determinism — production/development load real keys from Rails credentials.
+  config.active_record.encryption.primary_key = "test-primary-key-for-ar-encryption"
+  config.active_record.encryption.deterministic_key = "test-deterministic-key-for-ar-encryption"
+  config.active_record.encryption.key_derivation_salt = "test-key-derivation-salt-for-ar-encryption"
 end

data/config/initializers/time_nanoseconds.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Nanosecond conversion for Time objects. Replaces raw
+# Process.clock_gettime(CLOCK_REALTIME) calls so that
+# ActiveSupport's freeze_time / travel_to work in tests.
+class Time
+  # @return [Integer] nanoseconds since epoch
+  def to_ns
+    (to_r * 1_000_000_000).to_i
+  end
+end

data/db/migrate/20260326180000_rename_event_to_message.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+# Renames the persistence layer from Event to Message.
+#
+# Events are ephemeral bus signals; Messages are persisted records of what
+# was said, by whom, in which conversation. The Anthropic API calls them
+# "messages" — this rename aligns the codebase with the agent's vocabulary.
+#
+# See: thoughts/shared/notes/2026-03-24/narrative-design-for-agent-prompts.md
+class RenameEventToMessage < ActiveRecord::Migration[8.1]
+  def up
+    # --- FTS5: drop triggers and virtual table (references old table name) ---
+    execute "DROP TRIGGER IF EXISTS events_fts_insert"
+    execute "DROP TRIGGER IF EXISTS events_fts_delete"
+    execute "DROP TABLE IF EXISTS events_fts"
+
+    # --- Main table: events → messages ---
+    rename_table :events, :messages
+    rename_column :messages, :event_type, :message_type
+
+    # --- Pinned events → pinned messages ---
+    rename_table :pinned_events, :pinned_messages
+    rename_column :pinned_messages, :event_id, :message_id
+
+    # --- Join table: goal_pinned_events → goal_pinned_messages ---
+    rename_table :goal_pinned_events, :goal_pinned_messages
+    rename_column :goal_pinned_messages, :pinned_event_id, :pinned_message_id
+
+    # --- Snapshots: event range columns ---
+    rename_column :snapshots, :from_event_id, :from_message_id
+    rename_column :snapshots, :to_event_id, :to_message_id
+
+    # --- Sessions: event pointer columns ---
+    rename_column :sessions, :mneme_boundary_event_id, :mneme_boundary_message_id
+    rename_column :sessions, :mneme_snapshot_first_event_id, :mneme_snapshot_first_message_id
+    rename_column :sessions, :mneme_snapshot_last_event_id, :mneme_snapshot_last_message_id
+    rename_column :sessions, :recalled_event_ids, :recalled_message_ids
+    rename_column :sessions, :viewport_event_ids, :viewport_message_ids
+
+    # --- Recreate FTS5 virtual table with new names ---
+    execute <<~SQL
+      CREATE VIRTUAL TABLE messages_fts USING fts5(
+        searchable_text,
+        content='',
+        contentless_delete=1,
+        tokenize='porter unicode61'
+      );
+    SQL
+
+    execute <<~SQL
+      INSERT INTO messages_fts(rowid, searchable_text)
+      SELECT m.id,
+        CASE
+          WHEN m.message_type IN ('user_message', 'agent_message', 'system_message')
+            THEN json_extract(m.payload, '$.content')
+          WHEN m.message_type = 'tool_call' AND json_extract(m.payload, '$.tool_name') = 'think'
+            THEN json_extract(m.payload, '$.tool_input.thoughts')
+        END
+      FROM messages m
+      WHERE (m.message_type IN ('user_message', 'agent_message', 'system_message'))
+         OR (m.message_type = 'tool_call' AND json_extract(m.payload, '$.tool_name') = 'think');
+    SQL
+
+    execute <<~SQL
+      CREATE TRIGGER messages_fts_insert AFTER INSERT ON messages
+      WHEN NEW.message_type IN ('user_message', 'agent_message', 'system_message')
+        OR (NEW.message_type = 'tool_call' AND json_extract(NEW.payload, '$.tool_name') = 'think')
+      BEGIN
+        INSERT INTO messages_fts(rowid, searchable_text)
+        VALUES (
+          NEW.id,
+          CASE
+            WHEN NEW.message_type IN ('user_message', 'agent_message', 'system_message')
+              THEN json_extract(NEW.payload, '$.content')
+            WHEN NEW.message_type = 'tool_call'
+              THEN json_extract(NEW.payload, '$.tool_input.thoughts')
+          END
+        );
+      END;
+    SQL
+
+    execute <<~SQL
+      CREATE TRIGGER messages_fts_delete AFTER DELETE ON messages
+      WHEN OLD.message_type IN ('user_message', 'agent_message', 'system_message')
+        OR (OLD.message_type = 'tool_call' AND json_extract(OLD.payload, '$.tool_name') = 'think')
+      BEGIN
+        DELETE FROM messages_fts WHERE rowid = OLD.id;
+      END;
+    SQL
+  end
+
+  def down
+    # --- FTS5: drop new triggers and table ---
+    execute "DROP TRIGGER IF EXISTS messages_fts_insert"
+    execute "DROP TRIGGER IF EXISTS messages_fts_delete"
+    execute "DROP TABLE IF EXISTS messages_fts"
+
+    # --- Sessions: restore event pointer columns ---
+    rename_column :sessions, :mneme_boundary_message_id, :mneme_boundary_event_id
+    rename_column :sessions, :mneme_snapshot_first_message_id, :mneme_snapshot_first_event_id
+    rename_column :sessions, :mneme_snapshot_last_message_id, :mneme_snapshot_last_event_id
+    rename_column :sessions, :recalled_message_ids, :recalled_event_ids
+    rename_column :sessions, :viewport_message_ids, :viewport_event_ids
+
+    # --- Snapshots: restore event range columns ---
+    rename_column :snapshots, :from_message_id, :from_event_id
+    rename_column :snapshots, :to_message_id, :to_event_id
+
+    # --- Join table: goal_pinned_messages → goal_pinned_events ---
+    rename_column :goal_pinned_messages, :pinned_message_id, :pinned_event_id
+    rename_table :goal_pinned_messages, :goal_pinned_events
+
+    # --- Pinned messages → pinned events ---
+    rename_column :pinned_messages, :message_id, :event_id
+    rename_table :pinned_messages, :pinned_events
+
+    # --- Main table: messages → events ---
+    rename_column :messages, :message_type, :event_type
+    rename_table :messages, :events
+
+    # --- Recreate original FTS5 ---
+    execute <<~SQL
+      CREATE VIRTUAL TABLE events_fts USING fts5(
+        searchable_text,
+        content='',
+        contentless_delete=1,
+        tokenize='porter unicode61'
+      );
+    SQL
+
+    execute <<~SQL
+      INSERT INTO events_fts(rowid, searchable_text)
+      SELECT e.id,
+        CASE
+          WHEN e.event_type IN ('user_message', 'agent_message', 'system_message')
+            THEN json_extract(e.payload, '$.content')
+          WHEN e.event_type = 'tool_call' AND json_extract(e.payload, '$.tool_name') = 'think'
+            THEN json_extract(e.payload, '$.tool_input.thoughts')
+        END
+      FROM events e
+      WHERE (e.event_type IN ('user_message', 'agent_message', 'system_message'))
+         OR (e.event_type = 'tool_call' AND json_extract(e.payload, '$.tool_name') = 'think');
+    SQL
+
+    execute <<~SQL
+      CREATE TRIGGER events_fts_insert AFTER INSERT ON events
+      WHEN NEW.event_type IN ('user_message', 'agent_message', 'system_message')
+        OR (NEW.event_type = 'tool_call' AND json_extract(NEW.payload, '$.tool_name') = 'think')
+      BEGIN
+        INSERT INTO events_fts(rowid, searchable_text)
+        VALUES (
+          NEW.id,
+          CASE
+            WHEN NEW.event_type IN ('user_message', 'agent_message', 'system_message')
+              THEN json_extract(NEW.payload, '$.content')
+            WHEN NEW.event_type = 'tool_call'
+              THEN json_extract(NEW.payload, '$.tool_input.thoughts')
+          END
+        );
+      END;
+    SQL
+
+    execute <<~SQL
+      CREATE TRIGGER events_fts_delete AFTER DELETE ON events
+      WHEN OLD.event_type IN ('user_message', 'agent_message', 'system_message')
+        OR (OLD.event_type = 'tool_call' AND json_extract(OLD.payload, '$.tool_name') = 'think')
+      BEGIN
+        DELETE FROM events_fts WHERE rowid = OLD.id;
+      END;
+    SQL
+  end
+end

data/db/migrate/20260328100000_create_secrets.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+class CreateSecrets < ActiveRecord::Migration[8.1]
+  def change
+    create_table :secrets do |t|
+      t.string :namespace, null: false
+      t.string :key, null: false
+      t.text :value, null: false
+
+      t.timestamps
+    end
+
+    add_index :secrets, [:namespace, :key], unique: true
+  end
+end

data/db/migrate/20260328152142_add_evicted_at_to_goals.rb

@@ -0,0 +1,6 @@
+class AddEvictedAtToGoals < ActiveRecord::Migration[8.1]
+  def change
+    add_column :goals, :evicted_at, :datetime
+    add_index :goals, :evicted_at
+  end
+end

data/db/migrate/20260329120000_create_pending_messages.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+class CreatePendingMessages < ActiveRecord::Migration[8.1]
+  def change
+    create_table :pending_messages do |t|
+      t.references :session, null: false, foreign_key: true
+      t.text :content, null: false
+      t.timestamps
+    end
+  end
+end

data/lib/agent_loop.rb

@@ -6,22 +6,17 @@
 # Extracted from {TUI::Screens::Chat} so the same agent logic can run from
 # the TUI, a background job, or an Action Cable channel.
 #
-# @note Not thread-safe. Callers must serialize concurrent calls to {#process}
-#   (e.g. TUI uses a loading flag, future callers should use session-level locks).
+# @note Not thread-safe. Callers must serialize concurrent access
+#   (e.g. {AgentRequestJob} uses session-level processing locks).
 #
 # @example Basic usage
 #   loop = AgentLoop.new(session: session)
-#   loop.process("What files are in the current directory?")
+#   loop.run
 #   loop.finalize
 #
 # @example With dependency injection (testing)
 #   loop = AgentLoop.new(session: session, client: mock_client, registry: mock_registry)
-#   loop.process("hello")
-#
-# @example Background job usage (retry-safe)
-#   loop = AgentLoop.new(session: session)
-#   loop.run  # processes persisted session messages without emitting UserMessage
-#   loop.finalize
+#   loop.run
 class AgentLoop
   # @return [Session] the conversation session this loop operates on
   attr_reader :session
@@ -30,9 +25,9 @@ class AgentLoop
   # @param shell_session [ShellSession, nil] injectable persistent shell;
   #   created automatically if not provided
   # @param client [LLM::Client, nil] injectable LLM client;
-  #   created lazily on first {#process} call if not provided
+  #   created lazily on first {#run} call if not provided
   # @param registry [Tools::Registry, nil] injectable tool registry;
-  #   built lazily on first {#process} call if not provided
+  #   built lazily on first {#run} call if not provided
   def initialize(session:, shell_session: nil, client: nil, registry: nil)
     @session = session
     @shell_session = shell_session || ShellSession.new(session_id: session.id)
@@ -40,28 +35,6 @@ class AgentLoop
     @registry = registry
   end
 
-  # Runs the agent loop for a single user input.
-  #
-  # Persists the user event directly (the global Persister skips
-  # non-pending user messages because {AgentRequestJob} owns their
-  # lifecycle). Then emits a bus notification and delegates to {#run}.
-  # On error emits {Events::AgentMessage} with the error text.
-  #
-  # @param input [String] raw user input
-  # @return [String, nil] the agent's response text, or nil for blank input
-  def process(input)
-    text = input.to_s.strip
-    return if text.empty?
-
-    persist_user_event(text)
-    Events::Bus.emit(Events::UserMessage.new(content: text, session_id: @session.id))
-    run
-  rescue => error
-    error_message = "#{error.class}: #{error.message}"
-    Events::Bus.emit(Events::AgentMessage.new(content: error_message, session_id: @session.id))
-    error_message
-  end
-
   # Makes the first LLM API call to verify delivery. Called inside the
   # Bounce Back transaction — if this raises, the user event rolls back.
   #
@@ -127,7 +100,7 @@ class AgentLoop
 
   # Tool classes available to all sessions by default.
   # @return [Array<Class<Tools::Base>>]
-  STANDARD_TOOLS = [Tools::Bash, Tools::Read, Tools::Write, Tools::Edit, Tools::WebGet, Tools::Think, Tools::Remember].freeze
+  STANDARD_TOOLS = [Tools::Bash, Tools::Read, Tools::Write, Tools::Edit, Tools::WebGet, Tools::Think, Tools::Remember, Tools::Recall].freeze
 
   # Tools that bypass {Session#granted_tools} filtering.
   # The agent's reasoning depends on these regardless of task scope.
@@ -140,12 +113,9 @@ class AgentLoop
 
   private
 
-  # @see Session#create_user_event
-  def persist_user_event(content)
-    @session.create_user_event(content)
-  end
-
   # Assembles LLM options (system prompt, environment context).
+  # Broadcasts the full debug context (system prompt + tool schemas)
+  # to debug-mode TUI clients on every LLM request.
   # @return [Hash] options for {LLM::Client#chat_with_tools}
   def build_llm_options
     options = {}
@@ -154,6 +124,7 @@ class AgentLoop
     end
     prompt = @session.system_prompt(environment_context: env_context)
     options[:system] = prompt if prompt
+    @session.broadcast_debug_context(system: prompt, tools: @registry&.schemas)
     options
   end
 
@@ -172,10 +143,12 @@ class AgentLoop
 
     granted_standard_tools.each { |tool| registry.register(tool) }
 
-    unless @session.sub_agent?
+    if @session.sub_agent?
+      registry.register(Tools::MarkGoalCompleted)
+    else
       registry.register(Tools::SpawnSubagent)
       registry.register(Tools::SpawnSpecialist)
-      registry.register(Tools::RequestFeature)
+      registry.register(Tools::OpenIssue)
     end
 
     register_mcp_tools(registry)

data/lib/agents/definition.rb

@@ -12,7 +12,7 @@ module Agents
   #   ---
   #   name: codebase-analyzer
   #   description: Analyzes codebase implementation details.
-  #   tools: read, bash
+  #   tools: read_file, bash
   #   model: claude-sonnet-4-5
   #   ---
   #

data/lib/analytical_brain/runner.rb

@@ -9,7 +9,9 @@ module AnalyticalBrain
   # active depends on the session type:
   #
   # * **Parent sessions** — session naming, skill/workflow/goal management
-  # * **Child sessions** — sub-agent nickname assignment, skill/workflow/goal management
+  # * **Child sessions** — sub-agent nickname assignment, skill management
+  #   (goal tracking and workflows disabled — sub-agents manage their sole goal
+  #   via mark_goal_completed)
   #
   # Tools mutate the observed session directly (e.g. renaming it, activating
   # skills), but no trace of the brain's reasoning is persisted — events are
@@ -27,7 +29,7 @@ module AnalyticalBrain
           ──────────────────────────────
           SESSION NAMING
           ──────────────────────────────
-          Call rename_session when the topic becomes clear or shifts.
+          Name the session when the topic becomes clear. Rename if it shifts.
           Format: one emoji + 1-3 descriptive words.
         PROMPT
         tools: [Tools::RenameSession]
@@ -38,10 +40,10 @@ module AnalyticalBrain
           ──────────────────────────────
           SUB-AGENT NAMING
           ──────────────────────────────
-          Call assign_nickname to give this sub-agent a short, memorable nickname.
+          Give this sub-agent a memorable nickname based on its task.
           Format: 1-3 lowercase words joined by hyphens (e.g. "loop-sleuth", "api-scout").
-          Evocative of the task, fun, easy to type after @.
-          Generate EXACTLY ONE nickname. If taken, pick another — no numeric suffixes.
+          Evocative, fun, easy to type after @.
+          One nickname per call. If taken, pick another — no numeric suffixes.
         PROMPT
         tools: [Tools::AssignNickname]
       ),
@@ -51,8 +53,9 @@ module AnalyticalBrain
           ──────────────────────────────
           SKILL MANAGEMENT
           ──────────────────────────────
-          Call activate_skill when the conversation matches a skill's description.
-          Call deactivate_skill when the agent moves to a different domain.
+          Activate skills when the conversation signals intent — before the agent acts on it.
+          Late activation means the agent works without domain knowledge.
+          Deactivate when the agent moves to a different domain.
           Multiple skills can be active at once.
         PROMPT
         tools: [Tools::ActivateSkill, Tools::DeactivateSkill]
@@ -63,11 +66,11 @@ module AnalyticalBrain
           ──────────────────────────────
           WORKFLOW MANAGEMENT
           ──────────────────────────────
-          Call read_workflow when the user starts a multi-step task matching a workflow description.
-          Read the returned content and use judgment to create appropriate goals — not a mechanical 1:1 mapping.
+          Activate a workflow when the user starts a multi-step task that matches one.
+          Read the returned content and use judgment to create goals — not a mechanical 1:1 mapping.
           Adapt to context: skip irrelevant steps, add extra steps for unfamiliar areas.
-          Call deactivate_workflow when the workflow completes or the user shifts focus.
-          Only one workflow can be active at a time — activating a new one replaces the previous.
+          Deactivate the workflow when it completes or the user shifts focus.
+          Only one workflow active at a time — activating a new one replaces the previous.
         PROMPT
         tools: [Tools::ReadWorkflow, Tools::DeactivateWorkflow]
       ),
@@ -77,11 +80,11 @@ module AnalyticalBrain
           ──────────────────────────────
           GOAL TRACKING
           ──────────────────────────────
-          Call set_goal to create a root goal when the user starts a multi-step task.
-          Call set_goal with parent_goal_id to add sub-goals (TODO items) under it.
-          Call update_goal to refine a goal's description as understanding evolves.
-          Call finish_goal when the main agent completes work a goal describes.
-          Finishing a root goal cascades — all active sub-goals are completed too.
+          Create a root goal when the user starts a multi-step task.
+          Break it into sub-goals as the plan becomes clear.
+          Refine goal wording as understanding evolves.
+          Mark goals complete when the agent finishes the work they describe.
+          Completing a root goal cascades — all sub-goals are finished too.
           Never duplicate an existing goal — check the active goals list first.
         PROMPT
         tools: [Tools::SetGoal, Tools::UpdateGoal, Tools::FinishGoal]
@@ -89,22 +92,22 @@ module AnalyticalBrain
     }.freeze
 
     BASE_PROMPT = <<~PROMPT
-      You are a background automation that manages session metadata.
-      You MUST ONLY communicate through tool calls — NEVER output text.
-      Always finish by calling everything_is_ready.
+      You manage context for the main agent — skills, goals, workflows, and session names.
+      Watch the conversation and act when context needs updating.
+      Communicate only through tool calls — never output text.
     PROMPT
 
     COMPLETION_PROMPT = <<~PROMPT
       ──────────────────────────────
       COMPLETION
       ──────────────────────────────
-      Call everything_is_ready as your LAST tool call, every time.
-      If nothing needs changing, call it immediately as your only tool call.
+      Always finish with everything_is_ready.
+      If nothing needs attention, call it immediately.
     PROMPT
 
     # Which responsibilities activate for each session type.
     PARENT_RESPONSIBILITIES = %i[session_naming skill_management workflow_management goal_tracking].freeze
-    CHILD_RESPONSIBILITIES = %i[sub_agent_naming skill_management workflow_management goal_tracking].freeze
+    CHILD_RESPONSIBILITIES = %i[sub_agent_naming skill_management].freeze
 
     # @param session [Session] the session to observe and maintain
     # @param client [LLM::Client, nil] injectable LLM client (defaults to fast model)
@@ -118,7 +121,7 @@ module AnalyticalBrain
     end
 
     # Runs the analytical brain loop. Builds context from the session's
-    # recent events, calls the LLM with the session-appropriate tool set,
+    # recent messages, calls the LLM with the session-appropriate tool set,
     # and executes any tool calls against the session.
     #
     # Events emitted during tool execution are not persisted — the phantom
@@ -130,12 +133,12 @@ module AnalyticalBrain
       messages = build_messages
       sid = @session.id
       if messages.empty?
-        log.debug("session=#{sid} — no events, skipping")
+        log.debug("session=#{sid} — no messages, skipping")
         return
       end
 
       system = build_system_prompt
-      log.info("session=#{sid} — running (#{recent_events.size} events)")
+      log.info("session=#{sid} — running (#{recent_messages.size} messages)")
       log.debug("system prompt:\n#{system}")
       log.debug("user message:\n#{messages.first[:content]}")
 
@@ -162,18 +165,18 @@ module AnalyticalBrain
       active_responsibility_keys.map { |key| RESPONSIBILITIES.fetch(key) }
     end
 
-    # Builds a condensed transcript of recent events as a single user message.
+    # Builds a condensed transcript of recent messages as a single user message.
     # The framing differs by session type:
     #
     # * **Parent:** "The main session is working on this: [transcript]"
     # * **Child:** "A sub-agent has been spawned with this task: [transcript]"
     #
-    # @return [Array<Hash>] single-element messages array, or empty if no events
+    # @return [Array<Hash>] single-element messages array, or empty if no messages
     def build_messages
-      events = recent_events
-      return [] if events.empty?
+      messages = recent_messages
+      return [] if messages.empty?
 
-      transcript = events.filter_map { |event| EventDecorator.for(event)&.render("brain") }.join("\n")
+      transcript = messages.filter_map { |msg| MessageDecorator.for(msg)&.render("brain") }.join("\n")
 
       if @session.sub_agent?
         build_child_message(transcript)
@@ -189,7 +192,7 @@ module AnalyticalBrain
         #{transcript}
         ```
 
-        Observe the conversation and take action: manage goals, activate or deactivate relevant skills, read workflows when a multi-step task matches, rename the session if needed, then call everything_is_ready.
+        Review and take any needed actions, then call everything_is_ready.
       MSG
       [{role: "user", content: content}]
     end
@@ -201,17 +204,17 @@ module AnalyticalBrain
         #{transcript}
         ```
 
-        Assign a memorable nickname based on the task, activate relevant skills, then call everything_is_ready.
+        Assign a nickname and activate relevant skills, then call everything_is_ready.
       MSG
       [{role: "user", content: content}]
     end
 
-    # @return [Array<Event>] most recent events in chronological order
-    def recent_events
-      @session.events
-        .context_events
+    # @return [Array<Message>] most recent messages in chronological order
+    def recent_messages
+      @session.messages
+        .context_messages
         .reorder(id: :desc)
-        .limit(Anima::Settings.analytical_brain_event_window)
+        .limit(Anima::Settings.analytical_brain_message_window)
         .to_a
         .reverse
     end