anima-core 0.2.1 → 1.0.0

data/lib/analytical_brain/tools/finish_goal.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  module Tools
+    # Marks a goal as completed on the main session. Sets the status to
+    # "completed" and records the completion timestamp.
+    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.input_schema
+        {
+          type: "object",
+          properties: {
+            goal_id: {
+              type: "integer",
+              description: "ID of the goal to mark as completed"
+            }
+          },
+          required: %w[goal_id]
+        }
+      end
+
+      # @param main_session [Session] the session owning the goal
+      def initialize(main_session:, **)
+        @main_session = main_session
+      end
+
+      # @param input [Hash<String, Object>] with "goal_id"
+      # @return [String] confirmation message
+      # @return [Hash] with :error key on failure
+      def execute(input)
+        goal_id = input["goal_id"]
+        goal = @main_session.goals.find_by(id: goal_id)
+        return {error: "Goal not found (id: #{goal_id})"} unless goal
+
+        complete(goal)
+      end
+
+      private
+
+      # Marks the goal as completed. Root goals cascade completion to all
+      # active sub-goals within a single transaction so the after_commit
+      # broadcast includes the fully cascaded state.
+      #
+      # Returns an error for already-completed goals so the analytical
+      # 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?
+
+        Goal.transaction do
+          goal.update!(status: "completed", completed_at: Time.current)
+          goal.cascade_completion! if goal.root?
+        end
+        "Goal completed: #{goal.description} (id: #{id})"
+      end
+    end
+  end
+end

data/lib/analytical_brain/tools/read_workflow.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  module Tools
+    # Reads and activates a workflow on the main session.
+    # Returns the full workflow content so the brain can create goals from it.
+    # Also sets the workflow as active on the session, injecting its content
+    # into the main agent's "Your Expertise" section.
+    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.input_schema
+        {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Name of the workflow to read (from the available workflows list)"
+            }
+          },
+          required: %w[name]
+        }
+      end
+
+      # @param main_session [Session] the session to activate the workflow on
+      def initialize(main_session:, **)
+        @main_session = main_session
+      end
+
+      # @param input [Hash<String, Object>] with "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
+        return {error: "Workflow name cannot be blank"} if workflow_name.empty?
+
+        workflow = @main_session.activate_workflow(workflow_name)
+        format_workflow(workflow)
+      rescue Workflows::InvalidDefinitionError => error
+        {error: error.message}
+      end
+
+      private
+
+      def format_workflow(workflow)
+        <<~CONTENT
+          Workflow: #{workflow.name}
+          Description: #{workflow.description}
+
+          #{workflow.content}
+        CONTENT
+      end
+    end
+  end
+end

data/lib/analytical_brain/tools/rename_session.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  module Tools
+    # Renames the main session with an emoji and short descriptive name.
+    # Operates on the main session passed through the registry context,
+    # not on the phantom analytical brain session.
+    #
+    # The analytical brain calls this when a conversation's topic becomes
+    # clear or shifts significantly enough to warrant a new name.
+    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.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"
+            }
+          },
+          required: %w[emoji name]
+        }
+      end
+
+      # @param main_session [Session] the session to rename
+      def initialize(main_session:, **)
+        @main_session = main_session
+      end
+
+      # @param input [Hash<String, Object>] with "emoji" and "name" keys
+      # @return [String] confirmation message
+      # @return [Hash] with :error key on validation failure
+      def execute(input)
+        error = validate(input)
+        return error if error
+
+        full_name = build_name(input)
+        @main_session.update!(name: full_name)
+        "Session renamed to: #{full_name}"
+      end
+
+      private
+
+      def validate(input)
+        return {error: "Emoji cannot be blank"} if input["emoji"].to_s.strip.empty?
+        {error: "Name cannot be blank"} if input["name"].to_s.strip.empty?
+      end
+
+      def build_name(input)
+        "#{input["emoji"].to_s.strip} #{input["name"].to_s.strip}".truncate(255)
+      end
+    end
+  end
+end

data/lib/analytical_brain/tools/set_goal.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  module Tools
+    # Creates a goal on the main session. Root goals represent high-level
+    # objectives (semantic episodes); sub-goals are TODO-style steps within
+    # a root goal. The two-level hierarchy is enforced by the Goal model.
+    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.input_schema
+        {
+          type: "object",
+          properties: {
+            description: {
+              type: "string",
+              description: "What needs to be accomplished (1-2 sentences)"
+            },
+            parent_goal_id: {
+              type: "integer",
+              description: "ID of the parent goal (omit for root goals)"
+            }
+          },
+          required: %w[description]
+        }
+      end
+
+      # @param main_session [Session] the session to create the goal on
+      def initialize(main_session:, **)
+        @main_session = main_session
+      end
+
+      # @param input [Hash<String, Object>] with "description" and optional "parent_goal_id"
+      # @return [String] confirmation with goal ID
+      # @return [Hash] with :error key on validation failure
+      def execute(input)
+        description = input["description"].to_s.strip
+        return {error: "Description cannot be blank"} if description.empty?
+
+        goal = @main_session.goals.create!(
+          description: description,
+          parent_goal_id: input["parent_goal_id"]
+        )
+        format_confirmation(goal)
+      rescue ActiveRecord::RecordInvalid => error
+        {error: error.record.errors.full_messages.join(", ")}
+      end
+
+      private
+
+      def format_confirmation(goal)
+        prefix = goal.parent_goal_id ? "Sub-goal" : "Goal"
+        "#{prefix} created: #{goal.description} (id: #{goal.id})"
+      end
+    end
+  end
+end

data/lib/analytical_brain/tools/update_goal.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  module Tools
+    # Updates a goal's description on the main session.
+    #
+    # The analytical brain creates goals early when intent is vague, then
+    # refines them as the conversation clarifies scope — e.g. "implement auth"
+    # becomes "implement OAuth2 middleware for API endpoints". Without this
+    # tool the brain would have to choose between keeping a stale description
+    # or creating a duplicate goal.
+    #
+    # Completed goals cannot be updated; attempting to do so returns an error
+    # so the brain learns to check status before calling this tool.
+    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.input_schema
+        {
+          type: "object",
+          properties: {
+            goal_id: {
+              type: "integer",
+              description: "ID of the goal to update"
+            },
+            description: {
+              type: "string",
+              description: "New description for the goal (1-2 sentences)"
+            }
+          },
+          required: %w[goal_id description]
+        }
+      end
+
+      # @param main_session [Session] the session owning the goal
+      def initialize(main_session:, **)
+        @main_session = main_session
+      end
+
+      # @param input [Hash<String, Object>] with "goal_id" and "description"
+      # @return [String] confirmation message
+      # @return [Hash] with :error key on failure
+      def execute(input)
+        goal_id = input["goal_id"]
+        description = input["description"].to_s.strip
+        return {error: "Description cannot be blank"} if description.empty?
+
+        goal = @main_session.goals.find_by(id: goal_id)
+        return {error: "Goal not found (id: #{goal_id})"} unless goal
+        return {error: "Cannot update completed goal: #{goal.description} (id: #{goal_id})"} if goal.completed?
+
+        goal.update!(description: description)
+        "Goal updated: #{description} (id: #{goal_id})"
+      end
+    end
+  end
+end

data/lib/analytical_brain.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  # Dev-only logger that writes to log/analytical_brain.log.
+  # In non-development environments returns a null logger so
+  # call sites don't need conditionals.
+  #
+  # @return [Logger]
+  def self.logger
+    @logger ||= build_logger
+  end
+
+  def self.build_logger
+    return Logger.new(File::NULL) unless Rails.env.development?
+
+    Logger.new(Rails.root.join("log", "analytical_brain.log")).tap do |log|
+      log.formatter = proc { |severity, time, _progname, msg|
+        "[#{time.strftime("%H:%M:%S.%L")}] #{severity}  #{msg}\n"
+      }
+    end
+  end
+  private_class_method :build_logger
+end

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

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+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
+      # +${credential:key_name}+ syntax.
+      #
+      # @example Store a secret
+      #   anima mcp secrets set linear_api_key=sk-xxx
+      #
+      # @example List stored secret names
+      #   anima mcp secrets list
+      #
+      # @example Remove a secret
+      #   anima mcp secrets remove linear_api_key
+      class Secrets < Thor
+        def self.exit_on_failure?
+          true
+        end
+
+        desc "set KEY=VALUE", "Store an MCP secret in encrypted credentials"
+        def set(pair)
+          key, value = pair.split("=", 2)
+          unless value
+            say "Error: expected KEY=VALUE format, got '#{pair}'", :red
+            exit 1
+          end
+
+          require_mcp_secrets.set(key, value)
+          say "Stored secret '#{key}'.", :green
+        rescue ArgumentError => argument_error
+          say "Error: #{argument_error.message}", :red
+          exit 1
+        end
+
+        desc "list", "List stored MCP secret names (not values)"
+        def list
+          keys = require_mcp_secrets.list
+
+          if keys.empty?
+            say "No MCP secrets stored.", :yellow
+            say "Add one with: anima mcp secrets set KEY=VALUE"
+            return
+          end
+
+          keys.each { |key| say "  #{key}" }
+        end
+
+        desc "remove KEY", "Remove an MCP secret from encrypted credentials"
+        def remove(key)
+          secrets = require_mcp_secrets
+          unless secrets.list.include?(key)
+            say "Error: secret '#{key}' not found", :red
+            exit 1
+          end
+
+          secrets.remove(key)
+          say "Removed secret '#{key}'.", :green
+        end
+
+        private
+
+        def require_mcp_secrets
+          Anima.boot_rails!
+          require_relative "../../../mcp/secrets"
+          require_relative "../../../credential_store"
+          ::Mcp::Secrets
+        end
+      end
+    end
+  end
+end

data/lib/anima/cli/mcp.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "mcp/secrets"
+
+module Anima
+  class CLI < Thor
+    # CLI commands for managing MCP server configuration in
+    # +~/.anima/mcp.toml+. Mirrors the UX of +claude mcp+ commands.
+    class Mcp < Thor
+      def self.exit_on_failure?
+        true
+      end
+
+      desc "secrets SUBCOMMAND", "Manage MCP secrets in encrypted credentials"
+      subcommand "secrets", Secrets
+
+      desc "list", "List configured MCP servers with health status"
+      def list
+        config = build_config
+        raw_servers = config.all_servers
+
+        if raw_servers.empty?
+          say "No MCP servers configured.", :yellow
+          say "Add one with: anima mcp add <name> <url>"
+          return
+        end
+
+        interpolated = interpolated_lookup(config)
+        raw_servers.each { |server| display_server(server, interpolated[server["name"]]) }
+        config.warnings.each { |warning| say "  warning: #{warning}", :yellow }
+      end
+
+      desc "add NAME URL_OR_COMMAND", "Add an MCP server"
+      long_desc <<~DESC
+        Add an MCP server to ~/.anima/mcp.toml.
+
+        HTTP server:   anima mcp add <name> <url>
+        Stdio server:  anima mcp add <name> -- <command> [args...]
+
+        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.
+      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)"
+      def add(name, *rest)
+        if rest.empty?
+          say "Error: missing server URL or command.", :red
+          say ""
+          say "Usage:"
+          say "  anima mcp add <name> <url>                  # HTTP server"
+          say "  anima mcp add <name> -- <command> [args...]  # stdio server"
+          abort_command
+        end
+
+        store_secrets(options[:secret])
+        settings = build_settings(rest)
+        build_config.add_server(name, settings)
+        say "Added #{settings["transport"]} server '#{name}' (#{settings_target(settings)}).", :green
+      rescue ArgumentError => argument_error
+        say "Error: #{argument_error.message}", :red
+        abort_command
+      end
+
+      desc "remove NAME", "Remove an MCP server"
+      def remove(name)
+        build_config.remove_server(name)
+        say "Removed server '#{name}'.", :green
+      rescue ArgumentError => argument_error
+        say "Error: #{argument_error.message}", :red
+        abort_command
+      end
+
+      private
+
+      def abort_command
+        exit 1
+      end
+
+      def build_config
+        require_relative "../../mcp/config"
+        ::Mcp::Config.new
+      end
+
+      # Stores secrets from -s KEY=VALUE flags in encrypted credentials.
+      def store_secrets(secret_strings)
+        return unless secret_strings&.any?
+
+        pairs = parse_key_values(secret_strings, label: "secret")
+        Anima.boot_rails!
+        require_relative "../../mcp/secrets"
+        require_relative "../../credential_store"
+        pairs.each { |key, value| ::Mcp::Secrets.set(key, value) }
+      end
+
+      # Builds interpolated server lookup keyed by name for health checks.
+      def interpolated_lookup(config)
+        lookup = {}
+        populate_lookup(lookup, config.http_servers, "http")
+        populate_lookup(lookup, config.stdio_servers, "stdio")
+        lookup
+      end
+
+      def populate_lookup(lookup, servers, transport)
+        servers.each { |server| lookup[server[:name]] = server.merge(transport: transport) }
+      end
+
+      # Detects transport from arguments:
+      # - First arg starts with http(s):// → HTTP server
+      # - Otherwise → stdio server (command + args)
+      def build_settings(args)
+        first_arg = args.first
+        if first_arg.match?(%r{\Ahttps?://})
+          build_http_settings(first_arg)
+        else
+          build_stdio_settings(args)
+        end
+      end
+
+      def build_http_settings(url)
+        settings = {"transport" => "http", "url" => url}
+        headers = options[:header]
+        settings["headers"] = parse_headers(headers) if headers&.any?
+        settings
+      end
+
+      def build_stdio_settings(args)
+        command, *remaining_args = args
+        settings = {"transport" => "stdio", "command" => command}
+        settings["args"] = remaining_args if remaining_args.any?
+        env_vars = options[:env]
+        settings["env"] = parse_key_values(env_vars) if env_vars&.any?
+        settings
+      end
+
+      def settings_target(settings)
+        if settings["transport"] == "http"
+          settings["url"]
+        else
+          [settings["command"], *settings["args"]].join(" ")
+        end
+      end
+
+      def parse_headers(header_strings)
+        header_strings.to_h do |header|
+          key, value = header.split(": ", 2)
+          raise ArgumentError, "invalid header format '#{header}' — expected 'Name: Value'" unless value
+
+          [key, value]
+        end
+      end
+
+      def parse_key_values(kv_strings, label: "env var")
+        kv_strings.to_h do |kv|
+          key, value = kv.split("=", 2)
+          raise ArgumentError, "invalid #{label} format '#{kv}' — expected KEY=VALUE" unless value
+
+          [key, value]
+        end
+      end
+
+      def display_server(raw, interpolated)
+        name = raw["name"]
+        transport = raw["transport"]
+        detail = server_detail(raw, transport)
+        status = interpolated ? check_health(interpolated) : set_color("config error", :red)
+
+        say "  #{name}: #{detail} (#{transport}) — #{status}"
+      end
+
+      def server_detail(raw, transport)
+        case transport
+        when "http" then raw["url"]
+        when "stdio" then [raw["command"], *raw["args"]].compact.join(" ")
+        else "unknown transport '#{transport}'"
+        end
+      end
+
+      def check_health(server)
+        require_relative "../../mcp/health_check"
+        result = ::Mcp::HealthCheck.call(server)
+
+        case result[:status]
+        when :connected
+          set_color("connected (#{result[:tools]} tools)", :green)
+        when :failed
+          set_color("failed: #{result[:error]}", :red)
+        end
+      end
+    end
+  end
+end

data/lib/anima/cli.rb

@@ -2,6 +2,7 @@
 
 require "thor"
 require_relative "../anima"
+require_relative "cli/mcp"
 
 module Anima
   class CLI < Thor
@@ -47,17 +48,13 @@ module Anima
     option :host, desc: "Brain server address (default: #{DEFAULT_HOST})"
     def tui
       require "ratatui_ruby"
-      require "net/http"
-      require "json"
       require_relative "../tui/app"
 
       host = options[:host] || DEFAULT_HOST
 
       say "Connecting to brain at #{host}...", :cyan
-      session_id = fetch_current_session_with_retry(host)
-      say "Session ##{session_id} — starting TUI", :cyan
 
-      cable_client = TUI::CableClient.new(host: host, session_id: session_id)
+      cable_client = TUI::CableClient.new(host: host)
       cable_client.connect
 
       TUI::App.new(cable_client: cable_client).run
@@ -70,41 +67,9 @@ module Anima
       say "anima #{Anima::VERSION}"
     end
 
-    private
-
-    MAX_SESSION_FETCH_ATTEMPTS = 10
-    SESSION_FETCH_DELAY = 2 # seconds between retries
-
-    # Fetches the current session ID from the brain's REST API.
-    # Retries up to {MAX_SESSION_FETCH_ATTEMPTS} times if the brain is not running.
-    #
-    # @param host [String] brain server address
-    # @return [Integer] session ID
-    def fetch_current_session_with_retry(host)
-      attempts = 0
-      begin
-        fetch_current_session(host)
-      rescue Errno::ECONNREFUSED, Net::ReadTimeout, Net::OpenTimeout, SocketError => error
-        attempts += 1
-        if attempts >= MAX_SESSION_FETCH_ATTEMPTS
-          say "Cannot connect to brain after #{MAX_SESSION_FETCH_ATTEMPTS} attempts", :red
-          exit 1
-        end
-        say "Brain not available (#{error.class.name.split("::").last}). " \
-            "Retrying #{attempts}/#{MAX_SESSION_FETCH_ATTEMPTS}... (Ctrl+C to cancel)", :yellow
-        sleep SESSION_FETCH_DELAY
-        retry
-      end
-    end
+    desc "mcp SUBCOMMAND", "Manage MCP server configuration"
+    subcommand "mcp", Mcp
 
-    # Fetches the current session ID from the brain's REST API.
-    # @param host [String] brain server address
-    # @return [Integer] session ID
-    # @raise [RuntimeError] if the brain returns an error response
-    def fetch_current_session(host)
-      uri = URI("http://#{host}/api/sessions/current")
-      body = Net::HTTP.get(uri)
-      JSON.parse(body)["id"]
-    end
+    private
   end
 end