anima-core 0.2.1 → 1.0.0

data/lib/agents/definition.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Agents
+  class InvalidDefinitionError < StandardError; end
+
+  # A named sub-agent parsed from a Markdown definition file.
+  # YAML frontmatter holds metadata; the Markdown body is the system prompt.
+  #
+  # @example Definition file format
+  #   ---
+  #   name: codebase-analyzer
+  #   description: Analyzes codebase implementation details.
+  #   tools: read, bash
+  #   model: claude-sonnet-4-5
+  #   ---
+  #
+  #   You are a specialist at understanding HOW code works...
+  class Definition
+    # @return [String] unique agent identifier used in spawn_specialist(name: "...")
+    attr_reader :name
+
+    # @return [String] description shown to the LLM in the tool catalog
+    attr_reader :description
+
+    # @return [Array<String>] tool names available to this agent
+    attr_reader :tools
+
+    # @return [String] system prompt (Markdown body of the definition file)
+    attr_reader :prompt
+
+    # @return [String, nil] LLM model override (reserved for future use)
+    attr_reader :model
+
+    # @return [String, nil] TUI display color (reserved for future use)
+    attr_reader :color
+
+    # @return [Integer, nil] maximum conversation turns (reserved for future use)
+    attr_reader :max_turns
+
+    # @return [String] file path this definition was loaded from
+    attr_reader :source_path
+
+    def initialize(name:, description:, tools:, prompt:, model: nil, color: nil, max_turns: nil, source_path: "")
+      @name = name
+      @description = description
+      @tools = tools
+      @prompt = prompt
+      @model = model
+      @color = color
+      @max_turns = max_turns
+      @source_path = source_path
+    end
+
+    # Parses a Markdown file with YAML frontmatter into a Definition.
+    #
+    # @param path [String, Pathname] path to the .md file
+    # @return [Definition]
+    # @raise [InvalidDefinitionError] if required fields are missing or frontmatter is malformed
+    def self.from_file(path)
+      content = File.read(path)
+      frontmatter, body = parse_frontmatter(content)
+
+      validate_required_fields!(frontmatter, path)
+
+      new(
+        name: frontmatter["name"].to_s.strip,
+        description: frontmatter["description"].to_s.strip,
+        tools: parse_tools(frontmatter["tools"]),
+        prompt: body.strip,
+        model: frontmatter["model"]&.to_s&.strip,
+        color: frontmatter["color"]&.to_s&.strip,
+        max_turns: frontmatter["maxTurns"]&.to_i,
+        source_path: path.to_s
+      )
+    end
+
+    # @param content [String] raw file content with YAML frontmatter
+    # @return [Array(Hash, String)] parsed frontmatter and body text
+    # @raise [InvalidDefinitionError] if frontmatter is missing or malformed
+    def self.parse_frontmatter(content)
+      # Opening "---" must be followed by a newline (not just whitespace).
+      # Non-greedy (.*?\n) captures YAML lines up to the closing "---".
+      # Closing "---" may optionally be followed by a newline before the body.
+      # The /m flag lets (.*) in the body capture across newlines.
+      match = content.match(/\A---\s*\n(.*?\n)---\s*\n?(.*)\z/m)
+      raise InvalidDefinitionError, "Missing YAML frontmatter" unless match
+
+      frontmatter = YAML.safe_load(match[1])
+      raise InvalidDefinitionError, "Frontmatter is not a valid YAML mapping" unless frontmatter.is_a?(Hash)
+
+      [frontmatter, match[2]]
+    end
+
+    # Accepts comma-separated string or array of tool names.
+    #
+    # @param tools_value [String, Array, nil] raw tools field from frontmatter
+    # @return [Array<String>] normalized lowercase tool names
+    def self.parse_tools(tools_value)
+      return [] if tools_value.nil?
+
+      names = tools_value.is_a?(Array) ? tools_value : tools_value.to_s.split(",")
+      names.map { |tool| tool.to_s.strip.downcase }.reject(&:empty?).uniq
+    end
+
+    def self.validate_required_fields!(frontmatter, path)
+      %w[name description].each do |field|
+        value = frontmatter[field].to_s.strip
+        raise InvalidDefinitionError, "Missing required field '#{field}' in #{path}" if value.empty?
+      end
+    end
+
+    private_class_method :parse_frontmatter, :parse_tools, :validate_required_fields!
+  end
+end

data/lib/agents/registry.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Agents
+  # Loads named agent definitions from Markdown files and provides lookup.
+  # Scans two directories:
+  #   1. Built-in agents shipped with Anima (agents/ in the gem root)
+  #   2. User-defined agents (~/.anima/agents/)
+  # User agents override built-in ones when names collide.
+  class Registry
+    # @return [Hash{String => Definition}] loaded definitions keyed by name
+    attr_reader :agents
+
+    BUILTIN_DIR = File.expand_path("../../agents", __dir__).freeze
+    USER_DIR = File.expand_path("~/.anima/agents").freeze
+
+    def initialize
+      @agents = {}
+    end
+
+    # Returns the global registry, lazily loaded on first access.
+    #
+    # @return [Registry]
+    def self.instance
+      @instance ||= new.load_all
+    end
+
+    # Reloads the global registry from disk.
+    #
+    # @return [Registry]
+    def self.reload!
+      @instance = new.load_all
+    end
+
+    # Loads definitions from both built-in and user directories.
+    # User definitions override built-in ones with the same name.
+    #
+    # @return [self]
+    def load_all
+      load_directory(BUILTIN_DIR)
+      load_directory(USER_DIR)
+      self
+    end
+
+    # Loads agent definitions from a single directory.
+    #
+    # @param dir [String] directory path to scan for .md files
+    # @return [void]
+    def load_directory(dir)
+      return unless Dir.exist?(dir)
+
+      Dir.glob(File.join(dir, "*.md")).sort.each do |path|
+        definition = Definition.from_file(path)
+        validate_tools!(definition.name, definition.tools)
+        @agents[definition.name] = definition
+      rescue InvalidDefinitionError => error
+        warn "Skipping invalid agent definition #{path}: #{error.message}"
+      end
+    end
+
+    # Looks up a named agent definition.
+    #
+    # @param name [String] agent name
+    # @return [Definition, nil]
+    def get(name)
+      @agents[name]
+    end
+
+    # Agent names and descriptions for inclusion in tool documentation.
+    #
+    # @return [Hash{String => String}] name => description
+    def catalog
+      @agents.transform_values(&:description)
+    end
+
+    # @return [Array<String>] registered agent names
+    def names
+      @agents.keys
+    end
+
+    # @return [Boolean]
+    def any?
+      @agents.any?
+    end
+
+    # @return [Integer]
+    def size
+      @agents.size
+    end
+
+    private
+
+    # Validates that all declared tool names are recognized standard tools.
+    #
+    # @param agent_name [String] agent name for error messages
+    # @param tools [Array<String>] declared tool names
+    # @raise [InvalidDefinitionError] if any tool name is unknown
+    def validate_tools!(agent_name, tools)
+      return if tools.empty?
+
+      unknown = tools - AgentLoop::STANDARD_TOOLS_BY_NAME.keys
+      return if unknown.empty?
+
+      raise InvalidDefinitionError, "Unknown tools in '#{agent_name}': #{unknown.join(", ")}"
+    end
+  end
+end

data/lib/analytical_brain/runner.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  # Orchestrates the analytical brain — a phantom (non-persisted) LLM loop
+  # that observes a main session and performs background maintenance via tools.
+  #
+  # The analytical brain is a "subconscious" process: it operates ON the main
+  # session without the main agent knowing it exists. Tools mutate the main
+  # session directly (e.g. renaming it, activating skills), but no trace of
+  # the analytical brain's reasoning is persisted.
+  #
+  # @example
+  #   AnalyticalBrain::Runner.new(session).call
+  class Runner
+    # Tools available to the analytical brain.
+    # @return [Array<Class<Tools::Base>>]
+    TOOLS = [
+      Tools::RenameSession,
+      Tools::ActivateSkill,
+      Tools::DeactivateSkill,
+      Tools::ReadWorkflow,
+      Tools::DeactivateWorkflow,
+      Tools::SetGoal,
+      Tools::UpdateGoal,
+      Tools::FinishGoal,
+      Tools::EverythingIsReady
+    ].freeze
+
+    SYSTEM_PROMPT = <<~PROMPT
+      You are a background automation that manages session metadata.
+      You MUST ONLY communicate through tool calls — NEVER output text.
+      Always finish by calling everything_is_ready.
+
+      ──────────────────────────────
+      SESSION NAMING
+      ──────────────────────────────
+      Call rename_session when the topic becomes clear or shifts.
+      Format: one emoji + 1-3 descriptive words.
+
+      ──────────────────────────────
+      SKILL MANAGEMENT
+      ──────────────────────────────
+      Call activate_skill when the conversation matches a skill's description.
+      Call deactivate_skill when the agent moves to a different domain.
+      Multiple skills can be active at once.
+
+      ──────────────────────────────
+      WORKFLOW MANAGEMENT
+      ──────────────────────────────
+      Call read_workflow when the user starts a multi-step task matching a workflow description.
+      Read the returned content and use judgment to create appropriate goals — not a mechanical 1:1 mapping.
+      Adapt to context: skip irrelevant steps, add extra steps for unfamiliar areas.
+      Call deactivate_workflow when the workflow completes or the user shifts focus.
+      Only one workflow can be active at a time — activating a new one replaces the previous.
+
+      ──────────────────────────────
+      GOAL TRACKING
+      ──────────────────────────────
+      Call set_goal to create a root goal when the user starts a multi-step task.
+      Call set_goal with parent_goal_id to add sub-goals (TODO items) under it.
+      Call update_goal to refine a goal's description as understanding evolves.
+      Call finish_goal when the main agent completes work a goal describes.
+      Finishing a root goal cascades — all active sub-goals are completed too.
+      Never duplicate an existing goal — check the active goals list first.
+
+      ──────────────────────────────
+      COMPLETION
+      ──────────────────────────────
+      Call everything_is_ready as your LAST tool call, every time.
+      If nothing needs changing, call it immediately as your only tool call.
+    PROMPT
+
+    # @param session [Session] the main session to observe and maintain
+    # @param client [LLM::Client, nil] injectable LLM client (defaults to fast model)
+    def initialize(session, client: nil)
+      @session = session
+      @client = client || LLM::Client.new(
+        model: Anima::Settings.fast_model,
+        max_tokens: Anima::Settings.analytical_brain_max_tokens,
+        logger: AnalyticalBrain.logger
+      )
+    end
+
+    # Runs the analytical brain loop. Builds context from the main session's
+    # recent events, calls the LLM with the analytical brain's tool set, and
+    # executes any tool calls against the main session.
+    #
+    # Events emitted during tool execution are not persisted — the phantom
+    # session_id (nil) causes the global Persister to skip them.
+    #
+    # @return [String, nil] the LLM's final text response (discarded by caller),
+    #   or nil if no context is available
+    def call
+      messages = build_messages
+      sid = @session.id
+      if messages.empty?
+        log.debug("session=#{sid} — no events, skipping")
+        return
+      end
+
+      system = build_system_prompt
+      log.info("session=#{sid} — running (#{recent_events.size} events)")
+      log.debug("system prompt:\n#{system}")
+      log.debug("user message:\n#{messages.first[:content]}")
+
+      result = @client.chat_with_tools(
+        messages,
+        registry: build_registry,
+        session_id: nil,
+        system: system
+      )
+
+      log.info("session=#{sid} — done: #{result.to_s.truncate(200)}")
+      result
+    end
+
+    private
+
+    # Builds a condensed transcript of recent events as a single user message.
+    # The analytical brain doesn't need multi-turn conversation history — it
+    # just needs to understand "what is the agent doing RIGHT NOW?"
+    #
+    # The transcript is framed as an observation of the main session, not as
+    # a direct message to the analytical brain. Without this framing, Haiku
+    # confuses the main session's user messages with requests directed at it.
+    #
+    # @return [Array<Hash>] single-element messages array, or empty if no events
+    def build_messages
+      events = recent_events
+      return [] if events.empty?
+
+      transcript = events.filter_map { |event| format_event(event) }.join("\n")
+      content = <<~MSG.strip
+        The main session is working on this:
+        ```
+        #{transcript}
+        ```
+
+        Observe the conversation and take action: manage goals, activate or deactivate relevant skills, read workflows when a multi-step task matches, rename the session if needed, then call everything_is_ready.
+      MSG
+      [{role: "user", content: content}]
+    end
+
+    # @return [Array<Event>] most recent events in chronological order
+    def recent_events
+      @session.events
+        .context_events
+        .reorder(id: :desc)
+        .limit(Anima::Settings.analytical_brain_event_window)
+        .to_a
+        .reverse
+    end
+
+    # Formats a single event for the analytical brain's transcript.
+    # User/agent messages get 500 chars to preserve conversation context;
+    # tool responses get 200 chars to reduce noise from verbose outputs.
+    #
+    # @param event [Event]
+    # @return [String, nil] formatted line, or nil for unhandled event types
+    def format_event(event)
+      payload = event.payload
+      summary = payload["content"].to_s.truncate(500)
+
+      case event.event_type
+      when "user_message" then "User: #{summary}"
+      when "agent_message" then "Assistant: #{summary}"
+      when "tool_call" then "Tool call: #{payload["tool_name"]}"
+      when "tool_response" then "Tool result: #{summary.truncate(200)}"
+      end
+    end
+
+    # Builds the system prompt with current session state, skills catalog,
+    # and currently active skills.
+    #
+    # @return [String]
+    def build_system_prompt
+      sections = [
+        SYSTEM_PROMPT,
+        session_state_section,
+        skills_catalog_section,
+        workflows_catalog_section,
+        active_goals_section
+      ]
+      sections.compact.join("\n")
+    end
+
+    # @return [String] current session name, active skills, and active workflow
+    def session_state_section
+      name = @session.name || "(unnamed)"
+      skills = @session.active_skills.join(", ").presence || "None"
+      workflow = @session.active_workflow || "None"
+      <<~SECTION
+        ──────────────────────────────
+        CURRENT STATE
+        ──────────────────────────────
+        Session name: #{name}
+        Active skills: #{skills}
+        Active workflow: #{workflow}
+      SECTION
+    end
+
+    # @return [String] available skills list for the analytical brain
+    def skills_catalog_section
+      catalog = Skills::Registry.instance.catalog
+      items = if catalog.empty?
+        "None"
+      else
+        catalog.map { |name, desc| "- #{name} — #{desc}" }.join("\n")
+      end
+      <<~SECTION
+        ──────────────────────────────
+        AVAILABLE SKILLS
+        ──────────────────────────────
+        #{items}
+      SECTION
+    end
+
+    # @return [String] available workflows list for the analytical brain
+    def workflows_catalog_section
+      catalog = Workflows::Registry.instance.catalog
+      items = if catalog.empty?
+        "None"
+      else
+        catalog.map { |name, desc| "- #{name} — #{desc}" }.join("\n")
+      end
+      <<~SECTION
+        ──────────────────────────────
+        AVAILABLE WORKFLOWS
+        ──────────────────────────────
+        #{items}
+      SECTION
+    end
+
+    # @return [String, nil] active goals for the brain's own context,
+    #   so it knows what already exists and avoids duplicating
+    def active_goals_section
+      root_goals = @session.goals.root.includes(:sub_goals).active.order(:created_at)
+      return if root_goals.empty?
+
+      lines = root_goals.map { |goal| format_goal_for_brain(goal) }
+      <<~SECTION
+        ──────────────────────────────
+        ACTIVE GOALS
+        ──────────────────────────────
+        #{lines.join("\n")}
+      SECTION
+    end
+
+    # Formats a root goal and its sub-goals as a markdown checklist
+    # with IDs so the brain can reference them in finish_goal calls.
+    #
+    # @example
+    #   "- Implement feature X (id: 42)\n  - [x] Read code (id: 43)\n  - [ ] Write tests (id: 44)"
+    #
+    # @param goal [Goal] root goal with preloaded sub_goals
+    # @return [String] goal formatted as markdown checklist for brain context
+    def format_goal_for_brain(goal)
+      parts = ["- #{goal.description} (id: #{goal.id})"]
+      goal.sub_goals.sort_by(&:created_at).each do |sub|
+        checkbox = (sub.status == "completed") ? "[x]" : "[ ]"
+        parts << "  - #{checkbox} #{sub.description} (id: #{sub.id})"
+      end
+      parts.join("\n")
+    end
+
+    # @return [Logger] dev-only analytical brain logger
+    def log = AnalyticalBrain.logger
+
+    # @return [Tools::Registry] registry with analytical brain tools
+    def build_registry
+      registry = ::Tools::Registry.new(context: {main_session: @session})
+      TOOLS.each { |tool| registry.register(tool) }
+      registry
+    end
+  end
+end

data/lib/analytical_brain/tools/activate_skill.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  module Tools
+    # Activates a domain knowledge skill on the main session.
+    # The skill's content is injected into the main agent's system prompt,
+    # making the knowledge available for the current and future responses.
+    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.input_schema
+        {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Name of the skill to activate (from the available skills list)"
+            }
+          },
+          required: %w[name]
+        }
+      end
+
+      # @param main_session [Session] the session to activate the skill on
+      def initialize(main_session:, **)
+        @main_session = main_session
+      end
+
+      # @param input [Hash<String, Object>] with "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
+        return {error: "Skill name cannot be blank"} if skill_name.empty?
+
+        skill = @main_session.activate_skill(skill_name)
+        format_confirmation(skill)
+      rescue Skills::InvalidDefinitionError => error
+        {error: error.message}
+      end
+
+      private
+
+      def format_confirmation(skill)
+        "Activated skill: #{skill.name} (#{skill.description})"
+      end
+    end
+  end
+end

data/lib/analytical_brain/tools/deactivate_skill.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  module Tools
+    # Deactivates a domain knowledge skill on the main session.
+    # The skill's content is removed from the main agent's system prompt.
+    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.input_schema
+        {
+          type: "object",
+          properties: {
+            name: {
+              type: "string",
+              description: "Name of the skill to deactivate (from the currently active skills list)"
+            }
+          },
+          required: %w[name]
+        }
+      end
+
+      # @param main_session [Session] the session to deactivate the skill on
+      def initialize(main_session:, **)
+        @main_session = main_session
+      end
+
+      # @param input [Hash<String, Object>] with "name" key
+      # @return [String] confirmation message
+      # @return [Hash] with :error key on validation failure
+      def execute(input)
+        skill_name = input["name"].to_s.strip
+        return {error: "Skill name cannot be blank"} if skill_name.empty?
+
+        @main_session.deactivate_skill(skill_name)
+        "Deactivated skill: #{skill_name}"
+      end
+    end
+  end
+end

data/lib/analytical_brain/tools/deactivate_workflow.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  module Tools
+    # Deactivates the current workflow on the main session.
+    # The workflow's content is removed from the main agent's system prompt.
+    class DeactivateWorkflow < ::Tools::Base
+      def self.tool_name = "deactivate_workflow"
+
+      def self.description = "Deactivate the current workflow when it is complete or no longer relevant."
+
+      def self.input_schema
+        {
+          type: "object",
+          properties: {},
+          required: []
+        }
+      end
+
+      # @param main_session [Session] the session to deactivate the workflow on
+      def initialize(main_session:, **)
+        @main_session = main_session
+      end
+
+      # @param input [Hash<String, Object>] (no parameters needed)
+      # @return [String] confirmation message
+      def execute(_input)
+        previous = @main_session.active_workflow
+        @main_session.deactivate_workflow
+        previous ? "Deactivated workflow: #{previous}" : "No workflow was active"
+      end
+    end
+  end
+end

data/lib/analytical_brain/tools/everything_is_ready.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  module Tools
+    # Terminal tool that signals the analytical brain has completed its work.
+    # Call this when no changes are needed — the current session state is
+    # already good.
+    #
+    # After this tool returns, the LLM responds with text (not another
+    # tool call), naturally terminating the chat_with_tools loop.
+    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.input_schema
+        {type: "object", properties: {}, required: []}
+      end
+
+      # @param _input [Hash] ignored — this tool takes no input
+      # @return [String] confirmation message
+      def execute(_input)
+        "Acknowledged. No changes needed."
+      end
+    end
+  end
+end