anima-core 1.2.0 → 1.4.0

data/lib/tui/settings.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "toml-rb"
+
+module TUI
+  # TUI-specific configuration backed by +~/.anima/tui.toml+.
+  #
+  # Zero Rails dependency — the TUI is a standalone client process.
+  #
+  # Accessors are generated automatically from the template TOML file.
+  # Convention: method name = +section_key+ (e.g. +[hud] min_width+ →
+  # +hud_min_width+). To add a setting, add the key to +tui.toml+ — the
+  # accessor appears automatically.
+  #
+  # Settings are loaded once at startup. Restart the TUI to pick up
+  # changes — it's a thin client, the brain won't notice.
+  #
+  # @example Reading a setting
+  #   TUI::Settings.connection_default_host  #=> "localhost:42134"
+  #   TUI::Settings.hud_min_width            #=> 24
+  #
+  # @see Anima::Installer#create_tui_config creates the config file
+  module Settings
+    DEFAULT_PATH = File.expand_path("~/.anima/tui.toml")
+    TEMPLATE_PATH = File.expand_path("../../../templates/tui.toml", __FILE__)
+    TEMPLATE = TomlRB.load_file(TEMPLATE_PATH)
+
+    class MissingConfigError < StandardError; end
+    class MissingSettingError < StandardError; end
+
+    @config_path = nil
+
+    class << self
+      TEMPLATE.each do |section, keys|
+        keys.each_key { |key| attr_reader :"#{section}_#{key}" }
+      end
+
+      # Override config file path (for testing).
+      # Triggers a load so the new config takes effect immediately.
+      #
+      # @param path [String, nil] custom path, or +nil+ to restore default
+      def config_path=(path)
+        @config_path = path
+        load! if path
+      end
+
+      # @return [String] active config file path
+      def config_path
+        @config_path || DEFAULT_PATH
+      end
+
+      # Clears all loaded settings and resets to default path.
+      # Useful in test teardown.
+      def reset!
+        @config_path = nil
+        TEMPLATE.each do |section, keys|
+          keys.each_key { |key| instance_variable_set(:"@#{section}_#{key}", nil) }
+        end
+      end
+
+      # Parses the config file and populates all setting ivars.
+      #
+      # @raise [MissingConfigError] when tui.toml does not exist
+      # @raise [MissingSettingError] when a template key is missing from config
+      def load!
+        path = config_path
+        unless File.exist?(path)
+          raise MissingConfigError,
+            "TUI config file not found: #{path}. Run `anima install` to create it."
+        end
+
+        parsed = TomlRB.load_file(path)
+        TEMPLATE.each do |section, keys|
+          keys.each_key do |key|
+            value = parsed.dig(section, key)
+            if value.nil?
+              raise MissingSettingError,
+                "[#{section}] #{key} is not set in #{path}. Run `anima update` to add missing settings."
+            end
+            instance_variable_set(:"@#{section}_#{key}", value)
+          end
+        end
+      end
+    end
+  end
+end

data/skills/activerecord/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: activerecord
-description: "Associations, validations, queries, migrations, eager loading. Activate when working with models, database schema, N+1 queries, scopes, includes/preload/eager_load, callbacks, or editing app/models/ or db/migrate/."
+description: "Associations, validations, queries, migrations, eager loading, N+1 queries, scopes, callbacks, app/models/, db/migrate/."
 ---
 
 # ActiveRecord

data/skills/dragonruby/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dragonruby
-description: "2D game development — game loops, sprites, input, collisions, scenes. Activate when building games with DRGTK, working with args.outputs/state/inputs, or editing game files."
+description: "2D game development — game loops, sprites, input, collisions, scenes, DRGTK, args.outputs/state/inputs."
 ---
 
 # DragonRuby Game Toolkit

data/skills/draper-decorators/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: draper-decorators
-description: "Decorator patterns for Rails views — presentation logic separated from models. Activate when creating or testing decorators, moving formatting logic out of models/views, editing *_decorator.rb files, or working in app/decorators/."
+description: "Decorator patterns for Rails views — presentation logic separated from models, *_decorator.rb, app/decorators/."
 ---
 
 # Draper Decorators for Rails

data/skills/gh-issue.md

@@ -1,6 +1,6 @@
 ---
 name: gh-issue
-description: "Issue writing with WHAT/WHY/HOW framework. Activate when creating issues, writing tickets, drafting issue descriptions, or when issues lack clear rationale."
+description: "Issue writing with WHAT/WHY/HOW framework — tickets, bug reports, feature requests, issue descriptions, unclear rationale in existing issues."
 ---
 
 # GitHub Issue Writing

data/skills/mcp-server/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mcp-server
-description: "Ruby server development — tools, prompts, resources, transport. Activate when building Model Context Protocol servers, defining MCP tools/prompts/resources, working with the mcp gem, or discussing LLM tool integrations."
+description: "Ruby MCP server development — tools, prompts, resources, transport, the mcp gem, LLM tool integrations."
 ---
 
 # MCP Ruby SDK - Server Development Guide

data/skills/ratatui-ruby/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ratatui-ruby
-description: "Terminal UI development — widgets, layouts, events, Tea MVU. Activate when building TUI apps, working with terminal rendering, or editing TUI application files."
+description: "Terminal UI development — widgets, layouts, events, Tea MVU, terminal rendering."
 ---
 
 # RatatuiRuby

data/skills/rspec/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: rspec
-description: "Testing with FactoryBot — matchers, test doubles, shared examples. Activate when writing specs, fixing failing tests, working with describe/it/expect blocks, editing *_spec.rb files, planning test strategy, or discussing unit/integration tests."
+description: "Testing with FactoryBot — matchers, test doubles, shared examples, describe/it/expect blocks, *_spec.rb files, test strategy."
 ---
 
 # RSpec Testing

data/templates/config.toml

@@ -29,7 +29,18 @@ max_tool_rounds = 500
 
 # Context window budget — tokens reserved for conversation history.
 # Set this based on your model's context window minus system prompt.
-token_budget = 190_000
+token_budget = 120_000
+
+# Maximum character length for the Think tool's thoughts parameter.
+# Sub-agents receive half this budget (their tasks are less complex).
+thinking_budget = 10_000
+
+# Model for sub-agent sessions. Sonnet is cost-effective for focused tasks.
+subagent_model = "claude-sonnet-4-6"
+
+# Context window budget for sub-agent sessions.
+# Smaller than main to stay out of the "dumb zone" (~last 10% of context).
+subagent_token_budget = 90_000
 
 # ─── Timeouts (seconds) ─────────────────────────────────────────
 
@@ -51,6 +62,10 @@ web_request = 10
 # Also used as the default deadline for orphan detection in heal_orphaned_tool_calls!.
 tool = 180
 
+# How often (seconds) to poll for user interrupt during long-running commands.
+# Lower = faster Escape response, higher = less DB overhead.
+interrupt_check = 2
+
 # ─── Shell ──────────────────────────────────────────────────────
 
 [shell]
@@ -77,6 +92,16 @@ max_web_response_bytes = 100_000
 # Minimum characters of extracted content before flagging as possibly incomplete.
 min_web_content_chars = 100
 
+# Maximum characters of tool output before truncation (head + tail + temp file).
+# ~6000 chars ≈ ~2000 tokens. Most useful info fits in 10+10 lines; agent can
+# read the saved temp file for more.
+max_tool_response_chars = 6_000
+
+# Maximum characters of sub-agent result before truncation.
+# Sub-agent output is already curated — needs a generous but bounded limit.
+# ~24000 chars ≈ ~8000 tokens.
+max_subagent_response_chars = 24_000
+
 # ─── Environment ──────────────────────────────────────────────
 
 [environment]
@@ -155,6 +180,10 @@ l2_budget_fraction = 0.05
 # Number of uncovered Level 1 snapshots that triggers Level 2 compression.
 l2_snapshot_threshold = 5
 
+# Fraction of the viewport to evict in batch when Mneme runs.
+# Matches the viewport_fraction (Mneme's zone = eviction zone).
+eviction_fraction = 0.33
+
 # Fraction of the main viewport token budget reserved for pinned messages.
 # Pinned messages appear between snapshots and the sliding window in the Goals section.
 pinned_budget_fraction = 0.05

data/templates/tui.toml

@@ -0,0 +1,209 @@
+# TUI Configuration
+#
+# Presentation settings for the Anima terminal interface.
+# Changes take effect immediately — no restart needed.
+#
+# These settings only affect the TUI client, not the brain server.
+# Brain settings live in config.toml.
+
+# ─── Connection ──────────────────────────────────────────────────
+
+[connection]
+
+# Brain server address (host:port). Override per-launch with --host flag.
+default_host = "localhost:42134"
+
+# Seconds to wait for WebSocket thread cleanup on disconnect.
+disconnect_timeout = 2
+
+# Seconds between connection status checks during connect/reconnect.
+poll_interval = 0.1
+
+# Seconds before a connection attempt is considered timed out.
+timeout = 10
+
+# Maximum reconnection attempts before giving up.
+max_reconnect_attempts = 10
+
+# Initial delay before first reconnection attempt (seconds).
+# Doubles with each subsequent attempt up to backoff_cap.
+backoff_base = 1.0
+
+# Maximum delay between reconnection attempts (seconds).
+backoff_cap = 30.0
+
+# Seconds without an Action Cable ping before the connection is stale.
+ping_stale_threshold = 6.0
+
+# ─── HUD ─────────────────────────────────────────────────────────
+
+[hud]
+
+# Minimum width (columns) for the info panel.
+# The HUD occupies 1/3 of screen width, clamped to this minimum.
+min_width = 24
+
+# Lines scrolled per keyboard arrow event.
+scroll_step = 1
+
+# Lines scrolled per mouse wheel event.
+mouse_scroll_step = 2
+
+# ─── Chat ────────────────────────────────────────────────────────
+
+[chat]
+
+# Minimum height (rows) for the text input area.
+min_input_height = 3
+
+# Lines scrolled per keyboard arrow event.
+scroll_step = 1
+
+# Lines scrolled per mouse wheel event.
+mouse_scroll_step = 2
+
+# Entries rendered before scroll target for upward scroll margin.
+viewport_back_buffer = 3
+
+# Viewports worth of lines to pre-build for smooth scrolling.
+viewport_overflow_multiplier = 2
+
+# Entries from the end before including all trailing entries.
+viewport_bottom_threshold = 10
+
+# ─── Terminal ────────────────────────────────────────────────────
+
+[terminal]
+
+# How often the watchdog checks if the controlling terminal is alive (seconds).
+check_interval = 0.5
+
+# Grace period for watchdog thread to exit before force-killing it (seconds).
+shutdown_timeout = 1
+
+# ─── Token Dialog ────────────────────────────────────────────────
+
+[token_dialog]
+
+# Leading characters shown unmasked in the token input.
+# Default 14 matches the "sk-ant-oat01-" prefix plus one secret character.
+mask_visible = 14
+
+# Maximum stars shown in the masked portion.
+mask_stars = 4
+
+# Height (rows) of the token setup popup.
+popup_height = 14
+
+# Minimum width (columns) of the token setup popup.
+popup_min_width = 44
+
+# ─── Session Picker ──────────────────────────────────────────────
+
+[session_picker]
+
+# Sessions displayed per page.
+page_size = 9
+
+# Maximum sessions fetched from the brain for client-side pagination.
+fetch_limit = 50
+
+# ─── Flash ───────────────────────────────────────────────────────
+
+[flash]
+
+# Seconds before flash notifications auto-dismiss.
+auto_dismiss_seconds = 20.0
+
+# Flash area occupies at most 1/N of the chat pane height.
+max_height_fraction = 3
+
+# ─── Input ───────────────────────────────────────────────────────
+
+[input]
+
+# Maximum character length for the text input buffer.
+max_length = 10_000
+
+# ─── Message Store ───────────────────────────────────────────────
+
+[message_store]
+
+# Maximum cache history entries for sparkline rendering.
+# Each braille character encodes 2 data points, so 200 entries
+# render as ~100 characters.
+max_cache_history = 200
+
+# ─── Theme ────────────────────────────────────────────────────────
+
+[theme]
+
+# Progress bar width in characters.
+progress_bar_width = 8
+
+# Rate limit color thresholds (percentage).
+# Below warning = green, between warning and critical = yellow, above critical = red.
+rate_limit_warning = 70
+rate_limit_critical = 90
+
+# Cache hit color thresholds (percentage).
+# Above good = green, between low and good = yellow, below low = red.
+cache_hit_good = 70
+cache_hit_low = 30
+
+# Chat message background colors (256-color palette codes).
+# 22 = dark green (#005f00), 17 = dark navy (#00005f).
+# Full palette: https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit
+user_message_bg = 22
+assistant_message_bg = 17
+
+# Scrollbar colors.
+scrollbar_thumb = "cyan"
+scrollbar_track = "dark_gray"
+
+# Semantic colors — consistent visual language across the TUI.
+# Success (connected, completed, saved), error (disconnected, failed),
+# warning (connecting, loading, in-progress), info (labels, highlights),
+# muted (de-emphasized, idle, hints), accent (tool calls, special actions).
+color_success = "green"
+color_error = "red"
+color_warning = "yellow"
+color_info = "cyan"
+color_muted = "dark_gray"
+color_accent = "magenta"
+color_text = "white"
+
+# Selection highlight (session picker, menus).
+highlight_fg = "black"
+highlight_bg = "cyan"
+
+# Flash notification colors.
+flash_error_fg = "white"
+flash_error_bg = "red"
+flash_warning_fg = "black"
+flash_warning_bg = "yellow"
+flash_info_fg = "white"
+flash_info_bg = "blue"
+
+# Token count color for expensive responses (10k-20k tokens).
+# 208 = orange in 256-color palette.
+color_expensive = 208
+
+# Tool response CRUD colors — distinguish read/create/update at a glance.
+tool_read_color = "light_blue"
+tool_create_color = "light_green"
+tool_update_color = "light_yellow"
+
+# Border colors.
+border_focused = "yellow"
+border_normal = "white"
+border_input_connected = "green"
+border_input_connecting = "yellow"
+border_input_disconnected = "dark_gray"
+
+# ─── Performance ─────────────────────────────────────────────────
+
+[performance]
+
+# File path for TUI performance debug logs (relative to working directory).
+log_path = "log/tui_performance.log"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: anima-core
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.4.0
 platform: ruby
 authors:
 - Yevhenii Hurin
@@ -277,12 +277,17 @@ files:
 - app/models/goal.rb
 - app/models/goal_pinned_message.rb
 - app/models/message.rb
+- app/models/pending_message.rb
 - app/models/pinned_message.rb
+- app/models/secret.rb
 - app/models/session.rb
 - app/models/snapshot.rb
+- bin/inspect-cassette
 - bin/jobs
 - bin/rails
 - bin/rake
+- bin/release
+- bin/with-llms
 - config.ru
 - config/application.rb
 - config/boot.rb
@@ -293,13 +298,14 @@ files:
 - config/environments/production.rb
 - config/environments/test.rb
 - config/initializers/event_subscribers.rb
-- config/initializers/fts5_schema_dump.rb
 - config/initializers/inflections.rb
+- config/initializers/time_nanoseconds.rb
 - config/puma.rb
 - config/queue.yml
 - config/recurring.yml
 - config/routes.rb
 - db/cable_schema.rb
+- db/cable_structure.sql
 - db/migrate/.keep
 - db/migrate/20260308124202_create_sessions.rb
 - db/migrate/20260308124203_create_events.rb
@@ -324,8 +330,17 @@ files:
 - db/migrate/20260321140000_create_events_fts_index.rb
 - db/migrate/20260321140100_add_recalled_event_ids_to_sessions.rb
 - db/migrate/20260326180000_rename_event_to_message.rb
+- db/migrate/20260328100000_create_secrets.rb
+- db/migrate/20260328152142_add_evicted_at_to_goals.rb
+- db/migrate/20260329120000_create_pending_messages.rb
+- db/migrate/20260330120000_add_source_to_pending_messages.rb
+- db/migrate/20260401180000_add_api_metrics_to_messages.rb
+- db/migrate/20260401210935_remove_recalled_message_ids_from_sessions.rb
+- db/migrate/20260403080031_add_initial_cwd_to_sessions.rb
 - db/queue_schema.rb
+- db/queue_structure.sql
 - db/seeds.rb
+- db/structure.sql
 - exe/anima
 - lib/agent_loop.rb
 - lib/agents/definition.rb
@@ -338,6 +353,7 @@ files:
 - lib/analytical_brain/tools/deactivate_workflow.rb
 - lib/analytical_brain/tools/everything_is_ready.rb
 - lib/analytical_brain/tools/finish_goal.rb
+- lib/analytical_brain/tools/goal_messaging.rb
 - lib/analytical_brain/tools/read_workflow.rb
 - lib/analytical_brain/tools/rename_session.rb
 - lib/analytical_brain/tools/set_goal.rb
@@ -352,7 +368,6 @@ files:
 - lib/anima/spinner.rb
 - lib/anima/version.rb
 - lib/credential_store.rb
-- lib/environment_probe.rb
 - lib/events/agent_message.rb
 - lib/events/base.rb
 - lib/events/bounce_back.rb
@@ -389,11 +404,14 @@ files:
 - lib/tools/base.rb
 - lib/tools/bash.rb
 - lib/tools/edit.rb
+- lib/tools/mark_goal_completed.rb
 - lib/tools/mcp_tool.rb
 - lib/tools/open_issue.rb
 - lib/tools/read.rb
+- lib/tools/recall.rb
 - lib/tools/registry.rb
 - lib/tools/remember.rb
+- lib/tools/response_truncator.rb
 - lib/tools/spawn_specialist.rb
 - lib/tools/spawn_subagent.rb
 - lib/tools/subagent_prompts.rb
@@ -401,6 +419,7 @@ files:
 - lib/tools/web_get.rb
 - lib/tools/write.rb
 - lib/tui/app.rb
+- lib/tui/braille_spinner.rb
 - lib/tui/cable_client.rb
 - lib/tui/decorators/base_decorator.rb
 - lib/tui/decorators/bash_decorator.rb
@@ -416,6 +435,7 @@ files:
 - lib/tui/message_store.rb
 - lib/tui/performance_logger.rb
 - lib/tui/screens/chat.rb
+- lib/tui/settings.rb
 - lib/workflows/definition.rb
 - lib/workflows/registry.rb
 - skills/activerecord/SKILL.md
@@ -599,6 +619,7 @@ files:
 - skills/rspec/references/rails.md
 - templates/config.toml
 - templates/soul.md
+- templates/tui.toml
 - workflows/commit.md
 - workflows/create_handoff.md
 - workflows/create_note.md

data/config/initializers/fts5_schema_dump.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-# Skip FTS5 virtual tables during Ruby schema dump.
-# Rails' schema dumper can't express contentless FTS5 tables — the
-# migration handles creation. The schema.rb omits the virtual table,
-# and db:prepare runs pending migrations to recreate it.
-ActiveSupport.on_load(:active_record) do
-  require "active_record/connection_adapters/sqlite3/schema_dumper"
-
-  ActiveRecord::ConnectionAdapters::SQLite3::SchemaDumper.prepend(Module.new do
-    private
-
-    def virtual_tables(stream)
-      # Intentionally empty — FTS5 tables are managed by migrations.
-      # The default implementation crashes on contentless FTS5 arguments.
-    end
-  end)
-rescue LoadError
-  # Not using SQLite3 adapter — nothing to patch.
-  nil
-end