anima-core 1.1.3 → 1.3.0

data/lib/analytical_brain/tools/activate_skill.rb

@@ -8,19 +8,15 @@ module AnalyticalBrain
     class ActivateSkill < ::Tools::Base
       def self.tool_name = "activate_skill"
 
-      def self.description = "Activate a domain knowledge skill on the main session. " \
-        "The skill's content will be injected into the agent's system prompt."
+      def self.description = "Give the agent domain knowledge relevant to the current conversation."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            name: {
-              type: "string",
-              description: "Name of the skill to activate (from the available skills list)"
-            }
+            skill_name: {type: "string"}
           },
-          required: %w[name]
+          required: %w[skill_name]
         }
       end
 
@@ -29,11 +25,11 @@ module AnalyticalBrain
         @main_session = main_session
       end
 
-      # @param input [Hash<String, Object>] with "name" key
+      # @param input [Hash<String, Object>] with "skill_name" key
       # @return [String] confirmation message with skill description
       # @return [Hash] with :error key on validation failure
       def execute(input)
-        skill_name = input["name"].to_s.strip
+        skill_name = input["skill_name"].to_s.strip
         return {error: "Skill name cannot be blank"} if skill_name.empty?
 
         skill = @main_session.activate_skill(skill_name)

data/lib/analytical_brain/tools/assign_nickname.rb

@@ -17,8 +17,7 @@ module AnalyticalBrain
 
       def self.tool_name = "assign_nickname"
 
-      def self.description = "Assign a short, memorable nickname to this sub-agent. " \
-        "The nickname is permanent — it will not change."
+      def self.description = "Assign a permanent nickname to this sub-agent."
 
       def self.input_schema
         {
@@ -26,8 +25,7 @@ module AnalyticalBrain
           properties: {
             nickname: {
               type: "string",
-              description: "1-3 lowercase words joined by hyphens (e.g. 'loop-sleuth', 'api-scout'). " \
-                "Evocative of the task, fun, easy to type after @."
+              description: "Lowercase, hyphenated (e.g. 'loop-sleuth')."
             }
           },
           required: %w[nickname]

data/lib/analytical_brain/tools/deactivate_skill.rb

@@ -7,19 +7,15 @@ module AnalyticalBrain
     class DeactivateSkill < ::Tools::Base
       def self.tool_name = "deactivate_skill"
 
-      def self.description = "Deactivate a skill that is no longer relevant. " \
-        "The skill's content will be removed from the agent's system prompt."
+      def self.description = "Remove domain knowledge that is no longer relevant."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            name: {
-              type: "string",
-              description: "Name of the skill to deactivate (from the currently active skills list)"
-            }
+            skill_name: {type: "string"}
           },
-          required: %w[name]
+          required: %w[skill_name]
         }
       end
 
@@ -28,11 +24,11 @@ module AnalyticalBrain
         @main_session = main_session
       end
 
-      # @param input [Hash<String, Object>] with "name" key
+      # @param input [Hash<String, Object>] with "skill_name" key
       # @return [String] confirmation message
       # @return [Hash] with :error key on validation failure
       def execute(input)
-        skill_name = input["name"].to_s.strip
+        skill_name = input["skill_name"].to_s.strip
         return {error: "Skill name cannot be blank"} if skill_name.empty?
 
         @main_session.deactivate_skill(skill_name)

data/lib/analytical_brain/tools/everything_is_ready.rb

@@ -11,8 +11,7 @@ module AnalyticalBrain
     class EverythingIsReady < ::Tools::Base
       def self.tool_name = "everything_is_ready"
 
-      def self.description = "Signal that no changes are needed. " \
-        "Call this when the session name and active skills are already appropriate."
+      def self.description = "Nothing else to do."
 
       def self.input_schema
         {type: "object", properties: {}, required: []}

data/lib/analytical_brain/tools/finish_goal.rb

@@ -7,17 +7,13 @@ module AnalyticalBrain
     class FinishGoal < ::Tools::Base
       def self.tool_name = "finish_goal"
 
-      def self.description = "Mark a goal as completed. " \
-        "Use this when the main agent has finished the work described by the goal."
+      def self.description = "Mark a goal as completed."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            goal_id: {
-              type: "integer",
-              description: "ID of the goal to mark as completed"
-            }
+            goal_id: {type: "integer"}
           },
           required: %w[goal_id]
         }
@@ -49,7 +45,8 @@ module AnalyticalBrain
       # brain learns to check status before retrying.
       def complete(goal)
         id = goal.id
-        return {error: "Goal already completed: #{goal.description} (id: #{id})"} if goal.completed?
+        desc = goal.description
+        return {error: "Goal already completed: #{desc} (id: #{id})"} if goal.completed?
 
         released = 0
         Goal.transaction do
@@ -58,7 +55,7 @@ module AnalyticalBrain
           released = goal.release_orphaned_pins!
         end
 
-        msg = "Goal completed: #{goal.description} (id: #{id})"
+        msg = "Goal completed: #{desc} (id: #{id})"
         msg += " (released #{released} orphaned pins)" if released > 0
         msg
       end

data/lib/analytical_brain/tools/read_workflow.rb

@@ -9,19 +9,15 @@ module AnalyticalBrain
     class ReadWorkflow < ::Tools::Base
       def self.tool_name = "read_workflow"
 
-      def self.description = "Read a workflow's full content and activate it on the session. " \
-        "Use the content to create appropriate goals with set_goal."
+      def self.description = "Activate a workflow and return its content for goal planning."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            name: {
-              type: "string",
-              description: "Name of the workflow to read (from the available workflows list)"
-            }
+            workflow_name: {type: "string"}
           },
-          required: %w[name]
+          required: %w[workflow_name]
         }
       end
 
@@ -30,11 +26,11 @@ module AnalyticalBrain
         @main_session = main_session
       end
 
-      # @param input [Hash<String, Object>] with "name" key
+      # @param input [Hash<String, Object>] with "workflow_name" key
       # @return [String] workflow name, description, and full content
       # @return [Hash] with :error key on validation failure
       def execute(input)
-        workflow_name = input["name"].to_s.strip
+        workflow_name = input["workflow_name"].to_s.strip
         return {error: "Workflow name cannot be blank"} if workflow_name.empty?
 
         workflow = @main_session.activate_workflow(workflow_name)

data/lib/analytical_brain/tools/rename_session.rb

@@ -11,21 +11,14 @@ module AnalyticalBrain
     class RenameSession < ::Tools::Base
       def self.tool_name = "rename_session"
 
-      def self.description = "Rename the conversation session. " \
-        "Use one emoji followed by 1-3 descriptive words."
+      def self.description = "Rename the session."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            emoji: {
-              type: "string",
-              description: "A single emoji representing the conversation topic"
-            },
-            name: {
-              type: "string",
-              description: "1-3 word descriptive name for the session"
-            }
+            emoji: {type: "string"},
+            name: {type: "string", description: "1-3 words."}
           },
           required: %w[emoji name]
         }

data/lib/analytical_brain/tools/set_goal.rb

@@ -8,8 +8,7 @@ module AnalyticalBrain
     class SetGoal < ::Tools::Base
       def self.tool_name = "set_goal"
 
-      def self.description = "Create a goal on the main session. " \
-        "Omit parent_goal_id for a root goal, or provide it to create a sub-goal (TODO item)."
+      def self.description = "Create a goal or sub-goal."
 
       def self.input_schema
         {
@@ -17,12 +16,9 @@ module AnalyticalBrain
           properties: {
             description: {
               type: "string",
-              description: "What needs to be accomplished (1-2 sentences)"
+              description: "1 sentence."
             },
-            parent_goal_id: {
-              type: "integer",
-              description: "ID of the parent goal (omit for root goals)"
-            }
+            parent_goal_id: {type: "integer"}
           },
           required: %w[description]
         }

data/lib/analytical_brain/tools/update_goal.rb

@@ -15,20 +15,16 @@ module AnalyticalBrain
     class UpdateGoal < ::Tools::Base
       def self.tool_name = "update_goal"
 
-      def self.description = "Update a goal's description. " \
-        "Use this to refine a goal as understanding evolves."
+      def self.description = "Refine a goal's wording as understanding evolves."
 
       def self.input_schema
         {
           type: "object",
           properties: {
-            goal_id: {
-              type: "integer",
-              description: "ID of the goal to update"
-            },
+            goal_id: {type: "integer"},
             description: {
               type: "string",
-              description: "New description for the goal (1-2 sentences)"
+              description: "1 sentence."
             }
           },
           required: %w[goal_id description]

data/lib/anima/cli/mcp/secrets.rb

@@ -5,8 +5,8 @@ require "thor"
 module Anima
   class CLI < Thor
     class Mcp < Thor
-      # CLI commands for managing MCP secrets stored in Rails encrypted
-      # credentials. Secrets are referenced in mcp.toml via
+      # CLI commands for managing MCP secrets stored in the encrypted
+      # secrets table. Secrets are referenced in mcp.toml via
       # +${credential:key_name}+ syntax.
       #
       # @example Store a secret
@@ -22,7 +22,7 @@ module Anima
           true
         end
 
-        desc "set KEY=VALUE", "Store an MCP secret in encrypted credentials"
+        desc "set KEY=VALUE", "Store an MCP secret in encrypted secrets"
         def set(pair)
           key, value = pair.split("=", 2)
           unless value
@@ -50,7 +50,7 @@ module Anima
           keys.each { |key| say "  #{key}" }
         end
 
-        desc "remove KEY", "Remove an MCP secret from encrypted credentials"
+        desc "remove KEY", "Remove an MCP secret from encrypted storage"
         def remove(key)
           secrets = require_mcp_secrets
           unless secrets.list.include?(key)

data/lib/anima/cli/mcp.rb

@@ -12,7 +12,7 @@ module Anima
         true
       end
 
-      desc "secrets SUBCOMMAND", "Manage MCP secrets in encrypted credentials"
+      desc "secrets SUBCOMMAND", "Manage MCP secrets in encrypted storage"
       subcommand "secrets", Secrets
 
       desc "list", "List configured MCP servers with health status"
@@ -40,14 +40,14 @@ module Anima
 
         Use -e KEY=VALUE to set environment variables (stdio servers).
         Use -H "Header: Value" to set HTTP headers (HTTP servers).
-        Use -s KEY=VALUE to store a secret in encrypted credentials.
+        Use -s KEY=VALUE to store a secret in encrypted storage.
       DESC
       option :env, aliases: "-e", type: :string, repeatable: true, banner: "KEY=VALUE",
         desc: "Environment variables (repeatable)"
       option :header, aliases: "-H", type: :string, repeatable: true, banner: "Header: Value",
         desc: "HTTP headers (repeatable)"
       option :secret, aliases: "-s", type: :string, repeatable: true, banner: "KEY=VALUE",
-        desc: "Store secret in encrypted credentials (repeatable)"
+        desc: "Store secret in encrypted storage (repeatable)"
       def add(name, *rest)
         if rest.empty?
           say "Error: missing server URL or command.", :red
@@ -87,7 +87,7 @@ module Anima
         ::Mcp::Config.new
       end
 
-      # Stores secrets from -s KEY=VALUE flags in encrypted credentials.
+      # Stores secrets from -s KEY=VALUE flags in the encrypted secrets table.
       def store_secrets(secret_strings)
         return unless secret_strings&.any?
 

data/lib/anima/installer.rb

@@ -117,7 +117,13 @@ module Anima
           raise_if_missing_key: true
         )
 
-        config.write("secret_key_base: #{SecureRandom.hex(64)}\n")
+        config.write(<<~YAML)
+          secret_key_base: #{SecureRandom.hex(64)}
+          active_record_encryption:
+            primary_key: #{SecureRandom.base64(32)}
+            deterministic_key: #{SecureRandom.base64(32)}
+            key_derivation_salt: #{SecureRandom.base64(32)}
+        YAML
         File.chmod(0o600, content_str)
         say "  created credentials for #{env}"
       end

data/lib/anima/settings.rb

@@ -60,6 +60,13 @@ module Anima
         self.config_path = nil
       end
 
+      # ─── Agent Identity ─────────────────────────────────────────────
+
+      # The agent's display name. Separates engine identity ("Anima") from
+      # agent identity — any agent running on Anima can name itself.
+      # @return [String]
+      def agent_name = get("agent", "name")
+
       # ─── LLM ───────────────────────────────────────────────────────
 
       # Primary model for conversations.
@@ -84,6 +91,11 @@ module Anima
       # @return [Integer]
       def token_budget = get("llm", "token_budget")
 
+      # Maximum character length for the Think tool's thoughts parameter.
+      # Sub-agents receive half this budget (their tasks are less complex).
+      # @return [Integer]
+      def thinking_budget = get("llm", "thinking_budget")
+
       # ─── Timeouts (seconds) ────────────────────────────────────────
 
       # LLM API request timeout.
@@ -107,6 +119,13 @@ module Anima
       # @return [Integer] seconds
       def tool_timeout = get("timeouts", "tool")
 
+      # Polling interval for user interrupt checks during long-running commands.
+      # Enforces a 0.5s floor to prevent busy-polling from misconfiguration.
+      # @return [Numeric] seconds (minimum 0.5)
+      def interrupt_check_interval
+        [get("timeouts", "interrupt_check"), 0.5].max
+      end
+
       # ─── Shell ──────────────────────────────────────────────────────
 
       # Maximum bytes of command output before truncation.
@@ -119,11 +138,11 @@ module Anima
       # @return [Integer]
       def max_file_size = get("tools", "max_file_size")
 
-      # Maximum lines returned by the read tool.
+      # Maximum lines returned by the read_file tool.
       # @return [Integer]
       def max_read_lines = get("tools", "max_read_lines")
 
-      # Maximum bytes returned by the read tool.
+      # Maximum bytes returned by the read_file tool.
       # @return [Integer]
       def max_read_bytes = get("tools", "max_read_bytes")
 
@@ -131,6 +150,20 @@ module Anima
       # @return [Integer]
       def max_web_response_bytes = get("tools", "max_web_response_bytes")
 
+      # Minimum characters of extracted web content before flagging as possibly incomplete.
+      # @return [Integer]
+      def min_web_content_chars = get("tools", "min_web_content_chars")
+
+      # Maximum characters of tool output before head+tail truncation.
+      # Full output saved to a temp file for paginated reading.
+      # @return [Integer]
+      def max_tool_response_chars = get("tools", "max_tool_response_chars")
+
+      # Maximum characters of sub-agent result before head+tail truncation.
+      # Higher than tool threshold because sub-agent output is already curated.
+      # @return [Integer]
+      def max_subagent_response_chars = get("tools", "max_subagent_response_chars")
+
       # ─── Session ────────────────────────────────────────────────────
 
       # View mode applied to new sessions: "basic", "verbose", or "debug".
@@ -191,9 +224,16 @@ module Anima
       # @return [Boolean]
       def analytical_brain_blocking_on_agent_message = get("analytical_brain", "blocking_on_agent_message")
 
-      # Number of recent events to include in the analytical brain's context window.
+      # 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 ──────────────────────────────────────────────────────
+
+      # Number of meaningful messages (user + agent turns) after completion
+      # before a completed goal is automatically evicted from context.
       # @return [Integer]
-      def analytical_brain_event_window = get("analytical_brain", "event_window")
+      def completed_decay_messages = get("goals", "completed_decay_messages")
 
       # ─── Mneme (Memory Department) ────────────────────────────────
 
@@ -217,8 +257,8 @@ module Anima
       # @return [Integer]
       def mneme_l2_snapshot_threshold = get("mneme", "l2_snapshot_threshold")
 
-      # Fraction of the main viewport token budget reserved for pinned events.
-      # Pinned events appear between snapshots and the sliding window.
+      # Fraction of the main viewport token budget reserved for pinned messages.
+      # Pinned messages appear between snapshots and the sliding window.
       # @return [Float]
       def mneme_pinned_budget_fraction = get("mneme", "pinned_budget_fraction")
 

data/lib/anima/version.rb

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

data/lib/anima.rb

@@ -12,7 +12,7 @@ module Anima
   end
 
   # Boots Rails when CLI commands need access to Rails-managed resources
-  # like encrypted credentials. No-op if Rails is already loaded.
+  # like the encrypted secrets table. No-op if Rails is already loaded.
   def self.boot_rails!
     return if defined?(Rails)
 

data/lib/credential_store.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
-# Low-level read/write operations on Rails encrypted credentials.
-# Wraps the merge-and-write pattern used by {SessionChannel#write_anthropic_token}
-# in a reusable helper. All namespacing (e.g. +mcp+, +anthropic+) is the
-# caller's responsibility — this class operates on raw top-level keys.
+# Read/write operations for runtime secrets (API tokens, MCP credentials).
+# Backed by the {Secret} model with Active Record Encryption — values are
+# encrypted at rest and always fresh (no caching, no file-path issues in
+# forked Solid Queue workers).
+#
+# All namespacing (e.g. +mcp+, +anthropic+) is the caller's responsibility.
 #
 # @example Writing a nested credential
 #   CredentialStore.write("mcp", "linear_api_key" => "sk-xxx")
@@ -13,91 +15,40 @@
 class CredentialStore
   class << self
     # Writes one or more key-value pairs under a top-level namespace.
-    # Merges into existing credentials, preserving sibling keys.
+    # Upserts: existing keys are updated, new keys are created.
     #
-    # @param namespace [String] top-level YAML key (e.g. "mcp", "anthropic")
+    # @param namespace [String] top-level grouping key (e.g. "mcp", "anthropic")
     # @param pairs [Hash<String, String>] key-value pairs to store
     # @return [void]
     def write(namespace, pairs)
-      existing = load_credentials
-      section = existing[namespace] ||= {}
-      section.merge!(pairs)
-      save_credentials(existing)
+      Secret.write(namespace, pairs)
     end
 
     # Reads a single credential value from a namespace.
-    # Busts the Rails credentials cache first so cross-process writes
-    # (e.g. token saved in the web process, read in the SolidQueue worker)
-    # are always visible.
     #
-    # @param namespace [String] top-level YAML key
+    # @param namespace [String] top-level grouping key
     # @param key [String] credential key within the namespace
     # @return [String, nil] credential value or nil if not found
     def read(namespace, key)
-      bust_credentials_cache!
-      Rails.application.credentials.dig(namespace.to_sym, key.to_sym)
+      Secret.read(namespace, key)
     end
 
-    # Lists all keys under a namespace.
+    # Lists all keys under a namespace (not values).
     #
-    # @param namespace [String] top-level YAML key
-    # @return [Array<String>] credential keys (not values)
+    # @param namespace [String] top-level grouping key
+    # @return [Array<String>] credential keys
     def list(namespace)
-      section = Rails.application.credentials.dig(namespace.to_sym)
-      return [] unless section.is_a?(Hash)
-
-      section.keys.map(&:to_s)
+      Secret.list(namespace)
     end
 
     # Removes a single key from a namespace.
     # No-op if the key does not exist.
     #
-    # @param namespace [String] top-level YAML key
+    # @param namespace [String] top-level grouping key
     # @param key [String] credential key to remove
     # @return [void]
     def remove(namespace, key)
-      existing = load_credentials
-      section = existing[namespace]
-      return unless section.is_a?(Hash)
-      return unless section.key?(key)
-
-      section.delete(key)
-      existing.delete(namespace) if section.empty?
-      save_credentials(existing)
-    end
-
-    private
-
-    # Reads and parses the raw YAML from encrypted credentials.
-    # Returns an empty hash when the credentials file does not exist yet.
-    #
-    # @return [Hash] parsed credentials
-    def load_credentials
-      creds = Rails.application.credentials
-      YAML.safe_load(creds.read) || {}
-    rescue ActiveSupport::EncryptedFile::MissingContentError
-      {}
-    end
-
-    # Writes the full credentials hash back to the encrypted file and
-    # invalidates the Rails memoization cache so subsequent reads see
-    # fresh data.
-    #
-    # @param data [Hash] complete credentials hash to persist
-    # @return [void]
-    def save_credentials(data)
-      creds = Rails.application.credentials
-      creds.write(data.to_yaml)
-      bust_credentials_cache!
-    end
-
-    # Clears the Rails credentials in-memory cache so the next access
-    # re-reads and decrypts from disk. Required because Rails memoizes
-    # the decrypted config in @config per-process.
-    #
-    # @return [void]
-    def bust_credentials_cache!
-      Rails.application.credentials.instance_variable_set(:@config, nil)
+      Secret.remove(namespace, key)
     end
   end
 end

data/lib/events/base.rb

@@ -16,7 +16,7 @@ module Events
     def initialize(content:, session_id: nil)
       @content = content
       @session_id = session_id
-      @timestamp = Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
+      @timestamp = Time.current.to_ns
     end
 
     # @return [String] event type identifier

data/lib/events/bounce_back.rb

@@ -6,24 +6,24 @@ module Events
   # this event notifies clients to remove the phantom message and
   # restore the text to the input field.
   #
-  # Not persisted — not included in {Event::TYPES}.
+  # Not persisted — not included in {Message::TYPES}.
   class BounceBack < Base
     TYPE = "bounce_back"
 
     # @return [String] human-readable error description
     attr_reader :error
 
-    # @return [Integer, nil] database ID of the rolled-back event (for client-side removal)
-    attr_reader :event_id
+    # @return [Integer, nil] database ID of the rolled-back message (for client-side removal)
+    attr_reader :message_id
 
     # @param content [String] original user message text to restore to input
     # @param error [String] error description for the flash message
     # @param session_id [Integer] session the message was intended for
-    # @param event_id [Integer, nil] ID of the event that was broadcast optimistically
-    def initialize(content:, error:, session_id:, event_id: nil)
+    # @param message_id [Integer, nil] ID of the message that was broadcast optimistically
+    def initialize(content:, error:, session_id:, message_id: nil)
       super(content: content, session_id: session_id)
       @error = error
-      @event_id = event_id
+      @message_id = message_id
     end
 
     def type
@@ -31,7 +31,7 @@ module Events
     end
 
     def to_h
-      super.merge(error: error, event_id: event_id)
+      super.merge(error: error, message_id: message_id)
     end
   end
 end