anima-core 1.3.0 → 1.5.0

data/db/migrate/20260419130000_drop_pending_messages_kind_default.rb

@@ -0,0 +1,5 @@
+class DropPendingMessagesKindDefault < ActiveRecord::Migration[8.1]
+  def change
+    change_column_default :pending_messages, :kind, from: "active", to: nil
+  end
+end

data/db/migrate/20260419140000_add_drain_indexes_to_pending_messages.rb

@@ -0,0 +1,8 @@
+class AddDrainIndexesToPendingMessages < ActiveRecord::Migration[8.1]
+  def change
+    add_index :pending_messages, [:session_id, :message_type, :created_at],
+      name: "index_pending_messages_on_drain_ordering"
+    add_index :pending_messages, [:session_id, :tool_use_id],
+      name: "index_pending_messages_on_session_and_tool_use"
+  end
+end

data/db/migrate/20260420100000_add_hud_visibility_to_sessions.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Sub-agent sessions track presence in the parent's HUD panel through the
+# +hud_visible+ boolean. Mneme flips it to +false+ when viewport eviction
+# removes every trace of the sub-agent (spawn pair + response pairs). The
+# +spawn_tool_use_id+ column lets the trace query find the spawn pair
+# directly instead of string-matching the +spawn_subagent+ tool_input.
+class AddHudVisibilityToSessions < ActiveRecord::Migration[8.1]
+  def change
+    add_column :sessions, :hud_visible, :boolean, default: true, null: false
+    add_column :sessions, :spawn_tool_use_id, :string
+
+    add_index :sessions, [:parent_session_id, :hud_visible]
+  end
+end

data/db/queue_structure.sql

@@ -0,0 +1,61 @@
+CREATE TABLE "solid_queue_jobs" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "active_job_id" varchar, "arguments" text, "class_name" varchar NOT NULL, "concurrency_key" varchar, "created_at" datetime(6) NOT NULL, "finished_at" datetime(6), "priority" integer DEFAULT 0 NOT NULL, "queue_name" varchar NOT NULL, "scheduled_at" datetime(6), "updated_at" datetime(6) NOT NULL);
+CREATE INDEX "index_solid_queue_jobs_on_active_job_id" ON "solid_queue_jobs" ("active_job_id");
+CREATE INDEX "index_solid_queue_jobs_on_class_name" ON "solid_queue_jobs" ("class_name");
+CREATE INDEX "index_solid_queue_jobs_on_finished_at" ON "solid_queue_jobs" ("finished_at");
+CREATE INDEX "index_solid_queue_jobs_for_filtering" ON "solid_queue_jobs" ("queue_name", "finished_at");
+CREATE INDEX "index_solid_queue_jobs_for_alerting" ON "solid_queue_jobs" ("scheduled_at", "finished_at");
+CREATE TABLE "solid_queue_pauses" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "queue_name" varchar NOT NULL);
+CREATE UNIQUE INDEX "index_solid_queue_pauses_on_queue_name" ON "solid_queue_pauses" ("queue_name");
+CREATE TABLE "solid_queue_processes" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "hostname" varchar, "kind" varchar NOT NULL, "last_heartbeat_at" datetime(6) NOT NULL, "metadata" text, "name" varchar NOT NULL, "pid" integer NOT NULL, "supervisor_id" bigint);
+CREATE INDEX "index_solid_queue_processes_on_last_heartbeat_at" ON "solid_queue_processes" ("last_heartbeat_at");
+CREATE UNIQUE INDEX "index_solid_queue_processes_on_name_and_supervisor_id" ON "solid_queue_processes" ("name", "supervisor_id");
+CREATE INDEX "index_solid_queue_processes_on_supervisor_id" ON "solid_queue_processes" ("supervisor_id");
+CREATE TABLE "solid_queue_recurring_tasks" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "arguments" text, "class_name" varchar, "command" varchar(2048), "created_at" datetime(6) NOT NULL, "description" text, "key" varchar NOT NULL, "priority" integer DEFAULT 0, "queue_name" varchar, "schedule" varchar NOT NULL, "static" boolean DEFAULT TRUE NOT NULL, "updated_at" datetime(6) NOT NULL);
+CREATE UNIQUE INDEX "index_solid_queue_recurring_tasks_on_key" ON "solid_queue_recurring_tasks" ("key");
+CREATE INDEX "index_solid_queue_recurring_tasks_on_static" ON "solid_queue_recurring_tasks" ("static");
+CREATE TABLE "solid_queue_semaphores" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "expires_at" datetime(6) NOT NULL, "key" varchar NOT NULL, "updated_at" datetime(6) NOT NULL, "value" integer DEFAULT 1 NOT NULL);
+CREATE INDEX "index_solid_queue_semaphores_on_expires_at" ON "solid_queue_semaphores" ("expires_at");
+CREATE INDEX "index_solid_queue_semaphores_on_key_and_value" ON "solid_queue_semaphores" ("key", "value");
+CREATE UNIQUE INDEX "index_solid_queue_semaphores_on_key" ON "solid_queue_semaphores" ("key");
+CREATE TABLE "solid_queue_blocked_executions" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "concurrency_key" varchar NOT NULL, "created_at" datetime(6) NOT NULL, "expires_at" datetime(6) NOT NULL, "job_id" bigint NOT NULL, "priority" integer DEFAULT 0 NOT NULL, "queue_name" varchar NOT NULL, CONSTRAINT "fk_rails_4cd34e2228"
+FOREIGN KEY ("job_id")
+  REFERENCES "solid_queue_jobs" ("id")
+ ON DELETE CASCADE);
+CREATE INDEX "index_solid_queue_blocked_executions_for_release" ON "solid_queue_blocked_executions" ("concurrency_key", "priority", "job_id");
+CREATE INDEX "index_solid_queue_blocked_executions_for_maintenance" ON "solid_queue_blocked_executions" ("expires_at", "concurrency_key");
+CREATE UNIQUE INDEX "index_solid_queue_blocked_executions_on_job_id" ON "solid_queue_blocked_executions" ("job_id");
+CREATE TABLE "solid_queue_claimed_executions" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "job_id" bigint NOT NULL, "process_id" bigint, CONSTRAINT "fk_rails_9cfe4d4944"
+FOREIGN KEY ("job_id")
+  REFERENCES "solid_queue_jobs" ("id")
+ ON DELETE CASCADE);
+CREATE UNIQUE INDEX "index_solid_queue_claimed_executions_on_job_id" ON "solid_queue_claimed_executions" ("job_id");
+CREATE INDEX "index_solid_queue_claimed_executions_on_process_id_and_job_id" ON "solid_queue_claimed_executions" ("process_id", "job_id");
+CREATE TABLE "solid_queue_failed_executions" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "error" text, "job_id" bigint NOT NULL, CONSTRAINT "fk_rails_39bbc7a631"
+FOREIGN KEY ("job_id")
+  REFERENCES "solid_queue_jobs" ("id")
+ ON DELETE CASCADE);
+CREATE UNIQUE INDEX "index_solid_queue_failed_executions_on_job_id" ON "solid_queue_failed_executions" ("job_id");
+CREATE TABLE "solid_queue_ready_executions" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "job_id" bigint NOT NULL, "priority" integer DEFAULT 0 NOT NULL, "queue_name" varchar NOT NULL, CONSTRAINT "fk_rails_81fcbd66af"
+FOREIGN KEY ("job_id")
+  REFERENCES "solid_queue_jobs" ("id")
+ ON DELETE CASCADE);
+CREATE UNIQUE INDEX "index_solid_queue_ready_executions_on_job_id" ON "solid_queue_ready_executions" ("job_id");
+CREATE INDEX "index_solid_queue_poll_all" ON "solid_queue_ready_executions" ("priority", "job_id");
+CREATE INDEX "index_solid_queue_poll_by_queue" ON "solid_queue_ready_executions" ("queue_name", "priority", "job_id");
+CREATE TABLE "solid_queue_recurring_executions" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "job_id" bigint NOT NULL, "run_at" datetime(6) NOT NULL, "task_key" varchar NOT NULL, CONSTRAINT "fk_rails_318a5533ed"
+FOREIGN KEY ("job_id")
+  REFERENCES "solid_queue_jobs" ("id")
+ ON DELETE CASCADE);
+CREATE UNIQUE INDEX "index_solid_queue_recurring_executions_on_job_id" ON "solid_queue_recurring_executions" ("job_id");
+CREATE UNIQUE INDEX "index_solid_queue_recurring_executions_on_task_key_and_run_at" ON "solid_queue_recurring_executions" ("task_key", "run_at");
+CREATE TABLE "solid_queue_scheduled_executions" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "job_id" bigint NOT NULL, "priority" integer DEFAULT 0 NOT NULL, "queue_name" varchar NOT NULL, "scheduled_at" datetime(6) NOT NULL, CONSTRAINT "fk_rails_c4316f352d"
+FOREIGN KEY ("job_id")
+  REFERENCES "solid_queue_jobs" ("id")
+ ON DELETE CASCADE);
+CREATE UNIQUE INDEX "index_solid_queue_scheduled_executions_on_job_id" ON "solid_queue_scheduled_executions" ("job_id");
+CREATE INDEX "index_solid_queue_dispatch_all" ON "solid_queue_scheduled_executions" ("scheduled_at", "priority", "job_id");
+CREATE TABLE "schema_migrations" ("version" varchar NOT NULL PRIMARY KEY);
+CREATE TABLE "ar_internal_metadata" ("key" varchar NOT NULL PRIMARY KEY, "value" varchar, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL);
+INSERT INTO "schema_migrations" (version) VALUES
+('1');
+

data/db/structure.sql

@@ -0,0 +1,133 @@
+CREATE TABLE "secrets" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "key" varchar NOT NULL, "namespace" varchar NOT NULL, "updated_at" datetime(6) NOT NULL, "value" text NOT NULL);
+CREATE UNIQUE INDEX "index_secrets_on_namespace_and_key" ON "secrets" ("namespace", "key");
+CREATE TABLE "goals" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "completed_at" datetime(6), "created_at" datetime(6) NOT NULL, "description" text NOT NULL, "evicted_at" datetime(6), "parent_goal_id" integer, "session_id" integer NOT NULL, "status" varchar DEFAULT 'active' NOT NULL, "updated_at" datetime(6) NOT NULL, CONSTRAINT "fk_rails_feeb9df31e"
+FOREIGN KEY ("parent_goal_id")
+  REFERENCES "goals" ("id")
+, CONSTRAINT "fk_rails_874b7534ae"
+FOREIGN KEY ("session_id")
+  REFERENCES "sessions" ("id")
+);
+CREATE INDEX "index_goals_on_parent_goal_id" ON "goals" ("parent_goal_id");
+CREATE INDEX "index_goals_on_session_id_and_status" ON "goals" ("session_id", "status");
+CREATE INDEX "index_goals_on_session_id" ON "goals" ("session_id");
+CREATE TABLE "schema_migrations" ("version" varchar NOT NULL PRIMARY KEY);
+CREATE TABLE "ar_internal_metadata" ("key" varchar NOT NULL PRIMARY KEY, "value" varchar, "created_at" datetime(6) NOT NULL, "updated_at" datetime(6) NOT NULL);
+CREATE TABLE "messages" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "api_metrics" json, "created_at" datetime(6) NOT NULL, "message_type" varchar NOT NULL, "payload" json DEFAULT '{}' NOT NULL, "session_id" integer NOT NULL, "status" varchar, "timestamp" integer(8) NOT NULL, "token_count" integer DEFAULT 0 NOT NULL, "tool_use_id" varchar, "updated_at" datetime(6) NOT NULL, CONSTRAINT "fk_rails_1ee2a92df0"
+FOREIGN KEY ("session_id")
+  REFERENCES "sessions" ("id")
+);
+CREATE INDEX "index_messages_on_session_id_and_status" ON "messages" ("session_id", "status");
+CREATE INDEX "index_messages_on_session_id" ON "messages" ("session_id");
+CREATE INDEX "index_messages_on_tool_use_id" ON "messages" ("tool_use_id");
+CREATE INDEX "index_messages_on_message_type" ON "messages" ("message_type");
+CREATE INDEX "index_messages_on_session_id_and_message_type" ON "messages" ("session_id", "message_type");
+CREATE TABLE "pinned_messages" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "display_text" text NOT NULL, "message_id" integer NOT NULL, "updated_at" datetime(6) NOT NULL, "token_count" integer DEFAULT 0 NOT NULL, CONSTRAINT "fk_rails_4a5f237c43"
+FOREIGN KEY ("message_id")
+  REFERENCES "messages" ("id")
+);
+CREATE UNIQUE INDEX "index_pinned_messages_on_message_id" ON "pinned_messages" ("message_id");
+CREATE TABLE "goal_pinned_messages" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "goal_id" integer NOT NULL, "pinned_message_id" integer NOT NULL, "updated_at" datetime(6) NOT NULL, CONSTRAINT "fk_rails_689fd4bf8a"
+FOREIGN KEY ("goal_id")
+  REFERENCES "goals" ("id")
+, CONSTRAINT "fk_rails_fb51bfeebe"
+FOREIGN KEY ("pinned_message_id")
+  REFERENCES "pinned_messages" ("id")
+);
+CREATE INDEX "index_goal_pinned_messages_on_goal_id" ON "goal_pinned_messages" ("goal_id");
+CREATE UNIQUE INDEX "index_goal_pinned_messages_on_goal_id_and_pinned_message_id" ON "goal_pinned_messages" ("goal_id", "pinned_message_id");
+CREATE INDEX "index_goal_pinned_messages_on_pinned_message_id" ON "goal_pinned_messages" ("pinned_message_id");
+CREATE TABLE "snapshots" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "from_message_id" integer NOT NULL, "level" integer DEFAULT 1 NOT NULL, "session_id" integer NOT NULL, "text" text NOT NULL, "to_message_id" integer NOT NULL, "token_count" integer DEFAULT 0 NOT NULL, "updated_at" datetime(6) NOT NULL, CONSTRAINT "fk_rails_eb2ad51db9"
+FOREIGN KEY ("session_id")
+  REFERENCES "sessions" ("id")
+);
+CREATE INDEX "index_snapshots_on_session_and_event_range" ON "snapshots" ("session_id", "from_message_id", "to_message_id");
+CREATE INDEX "index_snapshots_on_session_id_and_level" ON "snapshots" ("session_id", "level");
+CREATE INDEX "index_snapshots_on_session_id" ON "snapshots" ("session_id");
+CREATE VIRTUAL TABLE messages_fts USING fts5(
+  searchable_text,
+  content='',
+  contentless_delete=1,
+  tokenize='porter unicode61'
+)
+/* messages_fts(searchable_text) */;
+CREATE TABLE 'messages_fts_data'(id INTEGER PRIMARY KEY, block BLOB);
+CREATE TABLE 'messages_fts_idx'(segid, term, pgno, PRIMARY KEY(segid, term)) WITHOUT ROWID;
+CREATE TABLE 'messages_fts_docsize'(id INTEGER PRIMARY KEY, sz BLOB, origin INTEGER);
+CREATE TABLE 'messages_fts_config'(k PRIMARY KEY, v) WITHOUT ROWID;
+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;
+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;
+CREATE TABLE "sessions" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "created_at" datetime(6) NOT NULL, "granted_tools" text, "interrupt_requested" boolean DEFAULT FALSE NOT NULL, "mneme_boundary_message_id" integer, "name" varchar, "parent_session_id" integer, "prompt" text, "recalled_message_ids" json DEFAULT '[]' NOT NULL, "updated_at" datetime(6) NOT NULL, "view_mode" varchar DEFAULT 'basic' NOT NULL, "initial_cwd" varchar, "aasm_state" varchar DEFAULT 'idle' NOT NULL, "hud_visible" boolean DEFAULT TRUE NOT NULL, "spawn_tool_use_id" varchar, CONSTRAINT "fk_rails_045409ac27"
+FOREIGN KEY ("parent_session_id")
+  REFERENCES "sessions" ("id")
+);
+CREATE UNIQUE INDEX "index_sessions_on_parent_and_name_unique" ON "sessions" ("parent_session_id", "name") WHERE name IS NOT NULL;
+CREATE INDEX "index_sessions_on_parent_session_id" ON "sessions" ("parent_session_id");
+CREATE TABLE "pending_messages" ("id" integer PRIMARY KEY AUTOINCREMENT NOT NULL, "content" text NOT NULL, "created_at" datetime(6) NOT NULL, "session_id" integer NOT NULL, "source_name" varchar, "source_type" varchar DEFAULT 'user' NOT NULL, "updated_at" datetime(6) NOT NULL, "kind" varchar NOT NULL, "message_type" varchar, "tool_use_id" varchar, "success" boolean, "bounce_back" boolean DEFAULT FALSE NOT NULL, CONSTRAINT "fk_rails_007242365b"
+FOREIGN KEY ("session_id")
+  REFERENCES "sessions" ("id")
+);
+CREATE INDEX "index_pending_messages_on_session_id" ON "pending_messages" ("session_id");
+CREATE INDEX "index_pending_messages_on_drain_ordering" ON "pending_messages" ("session_id", "message_type", "created_at");
+CREATE INDEX "index_pending_messages_on_session_and_tool_use" ON "pending_messages" ("session_id", "tool_use_id");
+CREATE INDEX "index_sessions_on_parent_session_id_and_hud_visible" ON "sessions" ("parent_session_id", "hud_visible");
+INSERT INTO "schema_migrations" (version) VALUES
+('20260420100000'),
+('20260419140000'),
+('20260419130000'),
+('20260419120000'),
+('20260418150323'),
+('20260412110625'),
+('20260411172926'),
+('20260411120553'),
+('20260407180400'),
+('20260407170803'),
+('20260403080031'),
+('20260401210935'),
+('20260401180000'),
+('20260330120000'),
+('20260329120000'),
+('20260328152142'),
+('20260328100000'),
+('20260326180000'),
+('20260321140100'),
+('20260321140000'),
+('20260321120000'),
+('20260321080000'),
+('20260316094817'),
+('20260315191105'),
+('20260315144837'),
+('20260315140843'),
+('20260315100000'),
+('20260314150000'),
+('20260314140000'),
+('20260314112417'),
+('20260314075248'),
+('20260313020000'),
+('20260313010000'),
+('20260312170000'),
+('20260308160000'),
+('20260308150000'),
+('20260308140000'),
+('20260308130000'),
+('20260308124203'),
+('20260308124202');
+

data/lib/agents/registry.rb

@@ -97,7 +97,7 @@ module Agents
     def validate_tools!(agent_name, tools)
       return if tools.empty?
 
-      unknown = tools - AgentLoop::STANDARD_TOOLS_BY_NAME.keys
+      unknown = tools - Tools::Registry::STANDARD_TOOLS_BY_NAME.keys
       return if unknown.empty?
 
       raise InvalidDefinitionError, "Unknown tools in '#{agent_name}': #{unknown.join(", ")}"

data/lib/anima/cli.rb

@@ -39,21 +39,29 @@ module Anima
       end
 
       require_relative "config_migrator"
-      result = Spinner.run("Migrating configuration...") do
+
+      result = Spinner.run("Migrating brain configuration...") do
         Anima::ConfigMigrator.new.run
       end
-
-      case result.status
-      when :not_found
+      if result.status == :not_found
         say "Config file not found. Run 'anima install' first.", :red
         exit 1
-      when :up_to_date
-        say "  Config is already up to date."
-      when :updated
-        result.additions.each do |addition|
-          say "  added [#{addition.section}] #{addition.key} = #{addition.value.inspect}"
-        end
       end
+      report_migration("Config", result)
+
+      tui_config_path = File.join(Anima::ConfigMigrator::ANIMA_HOME, "tui.toml")
+      tui_template = File.expand_path("../../templates/tui.toml", __dir__)
+      unless File.exist?(tui_config_path)
+        File.write(tui_config_path, File.read(tui_template))
+        say "  created #{tui_config_path} (new in this version)"
+      end
+      tui_result = Spinner.run("Migrating TUI configuration...") do
+        Anima::ConfigMigrator.new(
+          config_path: tui_config_path,
+          template_path: tui_template
+        ).run
+      end
+      report_migration("TUI config", tui_result)
 
       restart_service_if_active
     end
@@ -83,13 +91,15 @@ module Anima
     end
 
     desc "tui", "Launch the Anima terminal interface"
-    option :host, desc: "Brain server address (default: #{DEFAULT_HOST})"
-    option :debug, type: :boolean, default: false, desc: "Enable performance logging to log/tui_performance.log"
+    option :host, desc: "Brain server address (default: from tui.toml or #{DEFAULT_HOST})"
+    option :debug, type: :boolean, default: false, desc: "Enable performance logging"
     def tui
       require "ratatui_ruby"
+      require_relative "../tui/settings"
       require_relative "../tui/app"
 
-      host = options[:host] || DEFAULT_HOST
+      TUI::Settings.load!
+      host = options[:host] || TUI::Settings.connection_default_host
 
       say "Connecting to brain at #{host}...", :cyan
 
@@ -111,6 +121,24 @@ module Anima
 
     private
 
+    # Reports the outcome of a config migration to the user.
+    #
+    # @param label [String] human-readable config name (e.g. "Config", "TUI config")
+    # @param result [Anima::ConfigMigrator::Result] migration outcome
+    # @return [void]
+    def report_migration(label, result)
+      case result.status
+      when :not_found
+        say "#{label} file not found. Run 'anima install' first.", :red
+      when :up_to_date
+        say "  #{label} is already up to date."
+      when :updated
+        result.additions.each do |addition|
+          say "  added [#{addition.section}] #{addition.key} = #{addition.value.inspect}"
+        end
+      end
+    end
+
     # Restarts the systemd user service so updated code takes effect.
     # Without this, the service continues running the old gem version
     # until manually restarted (see #269).

data/lib/anima/installer.rb

@@ -31,6 +31,7 @@ module Anima
       create_directories
       create_soul_file
       create_settings_config
+      create_tui_config
       create_mcp_config
       generate_credentials
       create_systemd_service
@@ -68,6 +69,18 @@ module Anima
       say "  created #{config_path}"
     end
 
+    # Creates ~/.anima/tui.toml — TUI-specific presentation settings.
+    # Separate from config.toml because the TUI is a standalone client
+    # process with no Rails dependency.
+    def create_tui_config
+      config_path = anima_home.join("tui.toml")
+      return if config_path.exist?
+
+      template = File.read(File.join(TEMPLATE_DIR, "tui.toml"))
+      config_path.write(template)
+      say "  created #{config_path}"
+    end
+
     def create_mcp_config
       config_path = anima_home.join("mcp.toml")
       return if config_path.exist?

data/lib/anima/settings.rb

@@ -96,6 +96,15 @@ module Anima
       # @return [Integer]
       def thinking_budget = get("llm", "thinking_budget")
 
+      # Model for sub-agent sessions. Sonnet is cost-effective for focused tasks.
+      # @return [String] Anthropic model identifier
+      def subagent_model = get("llm", "subagent_model")
+
+      # Context window budget for sub-agent sessions.
+      # Smaller than main to keep sub-agents out of the "dumb zone".
+      # @return [Integer]
+      def subagent_token_budget = get("llm", "subagent_token_budget")
+
       # ─── Timeouts (seconds) ────────────────────────────────────────
 
       # LLM API request timeout.
@@ -179,26 +188,12 @@ module Anima
         value
       end
 
-      # Regenerate session name every N messages.
-      # @return [Integer]
-      def name_generation_interval = get("session", "name_generation_interval")
-
       # ─── Paths ───────────────────────────────────────────────────────
 
       # Path to the soul file — the agent's self-authored identity.
       # @return [String] absolute path
       def soul_path = get("paths", "soul")
 
-      # ─── Environment ──────────────────────────────────────────────
-
-      # Filenames to scan for in the working directory.
-      # @return [Array<String>]
-      def project_files_whitelist = get("environment", "project_files")
-
-      # Maximum directory depth for project file scanning.
-      # @return [Integer]
-      def project_files_max_depth = get("environment", "project_files_max_depth")
-
       # ─── GitHub ─────────────────────────────────────────────────────
 
       # Repository for feature requests (+owner/repo+ format).
@@ -210,30 +205,15 @@ module Anima
       # @return [String]
       def github_label = get("github", "label")
 
-      # ─── Analytical Brain ─────────────────────────────────────────
+      # ─── Melete ─────────────────────────────────────────
 
-      # Maximum tokens per analytical brain response.
+      # Maximum tokens per Melete response.
       # @return [Integer]
-      def analytical_brain_max_tokens = get("analytical_brain", "max_tokens")
-
-      # Run the analytical brain synchronously before the main agent on user messages.
-      # @return [Boolean]
-      def analytical_brain_blocking_on_user_message = get("analytical_brain", "blocking_on_user_message")
-
-      # Run the analytical brain asynchronously after the main agent completes.
-      # @return [Boolean]
-      def analytical_brain_blocking_on_agent_message = get("analytical_brain", "blocking_on_agent_message")
-
-      # Number of recent messages to include in the analytical brain's context window.
-      # @return [Integer]
-      def analytical_brain_message_window = get("analytical_brain", "message_window")
-
-      # ─── Goals ──────────────────────────────────────────────────────
+      def melete_max_tokens = get("melete", "max_tokens")
 
-      # Number of meaningful messages (user + agent turns) after completion
-      # before a completed goal is automatically evicted from context.
+      # Number of recent messages to include in Melete's context window.
       # @return [Integer]
-      def completed_decay_messages = get("goals", "completed_decay_messages")
+      def melete_message_window = get("melete", "message_window")
 
       # ─── Mneme (Memory Department) ────────────────────────────────
 
@@ -241,9 +221,9 @@ module Anima
       # @return [Integer]
       def mneme_max_tokens = get("mneme", "max_tokens")
 
-      # Fraction of the main viewport token budget allocated to Mneme's viewport.
+      # Fraction of the main token budget for Mneme's eviction zone.
       # @return [Float]
-      def mneme_viewport_fraction = get("mneme", "viewport_fraction")
+      def eviction_fraction = get("mneme", "eviction_fraction")
 
       # Fraction of the main viewport token budget reserved for L1 snapshots.
       # @return [Float]

data/lib/anima/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Anima
-  VERSION = "1.3.0"
+  VERSION = "1.5.0"
 end

data/lib/events/authentication_required.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted when the Anthropic provider rejects the configured token with
+  # an authentication error. Surfaces to the TUI via
+  # {Events::Subscribers::AuthenticationBroadcaster} so the user is
+  # prompted for a new token — and to the conversation as a system
+  # message so the failure is visible in history.
+  #
+  # Not persisted — not included in {Message::TYPES}.
+  class AuthenticationRequired < Base
+    TYPE = "authentication_required"
+
+    # @param session_id [Integer] session the failure is scoped to
+    # @param content [String] human-readable error text from the provider
+    def initialize(session_id:, content:)
+      super(content: content, session_id: session_id)
+    end
+
+    def type
+      TYPE
+    end
+  end
+end

data/lib/events/bounce_back.rb

@@ -1,10 +1,10 @@
 # frozen_string_literal: true
 
 module Events
-  # Transient failure event emitted when LLM delivery fails inside the
-  # Bounce Back transaction. The user event record is rolled back, and
-  # this event notifies clients to remove the phantom message and
-  # restore the text to the input field.
+  # Transient failure event emitted by {DrainJob} when the first LLM
+  # call on a bounce-back-flagged user_message fails. The promoted
+  # Message is destroyed so the TUI can remove the phantom and restore
+  # the user's text to the input field.
   #
   # Not persisted — not included in {Message::TYPES}.
   class BounceBack < Base

data/lib/events/eviction_completed.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after Mneme advances the boundary past an eviction zone.
+  # Subscribers broadcast the cutoff to connected clients so they can
+  # drop messages below it.
+  class EvictionCompleted
+    TYPE = "eviction.completed"
+
+    attr_reader :session_id, :evict_above_id
+
+    # @param session_id [Integer] the session whose boundary advanced
+    # @param evict_above_id [Integer] last message ID in the evicted zone;
+    #   clients drop all messages with id <= this value
+    def initialize(session_id:, evict_above_id:)
+      @session_id = session_id
+      @evict_above_id = evict_above_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, evict_above_id:}
+    end
+  end
+end

data/lib/events/goal_created.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after a {Goal} record is committed for the first time.
+  # The drain pipeline's {MeleteEnrichmentJob} subscribes for the
+  # duration of one Melete run so a fresh goal triggers Mneme recall
+  # against the updated goal set before the user's message reaches the LLM.
+  class GoalCreated
+    TYPE = "goal.created"
+
+    attr_reader :session_id, :goal_id
+
+    # @param session_id [Integer] session that owns the goal
+    # @param goal_id [Integer] the newly created goal
+    def initialize(session_id:, goal_id:)
+      @session_id = session_id
+      @goal_id = goal_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, goal_id:}
+    end
+  end
+end

data/lib/events/goal_updated.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after a {Goal}'s description is changed and the change is
+  # committed. Status-only updates (finish_goal, cascade completion,
+  # mark_goal_completed) do not emit — a completed goal carries no new
+  # search seed for Mneme.
+  #
+  # The drain pipeline's {MeleteEnrichmentJob} subscribes for the
+  # duration of one Melete run so a refined goal triggers Mneme recall
+  # against the updated wording before the user's message reaches the LLM.
+  class GoalUpdated
+    TYPE = "goal.updated"
+
+    attr_reader :session_id, :goal_id
+
+    # @param session_id [Integer] session that owns the goal
+    # @param goal_id [Integer] the updated goal
+    def initialize(session_id:, goal_id:)
+      @session_id = session_id
+      @goal_id = goal_id
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, goal_id:}
+    end
+  end
+end

data/lib/events/llm_responded.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted by the drain loop after a single LLM round-trip completes.
+  # Carries the raw Anthropic response so downstream subscribers can
+  # persist messages, transition session state, and dispatch tool
+  # execution when the response is a +tool_use+.
+  #
+  # The drain loop hands off via this event — it does not persist
+  # Messages or release the session itself. Single responsibility:
+  # one subscriber pumps PendingMessages into the LLM, another owns
+  # the aftermath.
+  class LLMResponded
+    TYPE = "session.llm_responded"
+
+    attr_reader :session_id, :response, :api_metrics
+
+    # @param session_id [Integer] session that made the LLM call
+    # @param response [Hash] raw Anthropic response (with +content+ and +stop_reason+)
+    # @param api_metrics [Hash, nil] rate-limit and usage metrics from the provider
+    def initialize(session_id:, response:, api_metrics: nil)
+      @session_id = session_id
+      @response = response
+      @api_metrics = api_metrics
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, session_id:, response:, api_metrics:}
+    end
+  end
+end

data/lib/events/message_created.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Events
+  # Emitted after a Message record is committed to the database.
+  # Subscribers react to persisted messages — not to raw domain events.
+  #
+  # Carries the Message record directly so subscribers don't need to
+  # look it up again.
+  class MessageCreated
+    TYPE = "message.created"
+
+    attr_reader :message
+
+    # @param message [Message] the persisted message record
+    def initialize(message)
+      @message = message
+    end
+
+    def event_name
+      "#{Bus::NAMESPACE}.#{TYPE}"
+    end
+
+    def to_h
+      {type: TYPE, message:}
+    end
+  end
+end