anima-core 1.0.1 → 1.1.0

data/lib/agent_loop.rb

@@ -42,7 +42,9 @@ class AgentLoop
 
   # Runs the agent loop for a single user input.
   #
-  # Emits {Events::UserMessage} immediately, then delegates to {#run}.
+  # Persists the user event directly (the global Persister skips
+  # non-pending user messages because {AgentRequestJob} owns their
+  # lifecycle). Then emits a bus notification and delegates to {#run}.
   # On error emits {Events::AgentMessage} with the error text.
   #
   # @param input [String] raw user input
@@ -51,6 +53,7 @@ class AgentLoop
     text = input.to_s.strip
     return if text.empty?
 
+    persist_user_event(text)
     Events::Bus.emit(Events::UserMessage.new(content: text, session_id: @session.id))
     run
   rescue => error
@@ -59,13 +62,41 @@ class AgentLoop
     error_message
   end
 
+  # Makes the first LLM API call to verify delivery. Called inside the
+  # Bounce Back transaction — if this raises, the user event rolls back.
+  #
+  # Caches the first response so the subsequent {#run} call can continue
+  # from it without duplicating the API call.
+  #
+  # @return [void]
+  # @raise [Providers::Anthropic::Error] on any LLM delivery failure
+  def deliver!
+    @client ||= LLM::Client.new
+    @registry ||= build_tool_registry
+
+    messages = @session.messages_for_llm
+    options = build_llm_options
+
+    @first_response = @client.provider.create_message(
+      model: @client.model,
+      messages: messages,
+      max_tokens: @client.max_tokens,
+      tools: @registry.schemas,
+      **options
+    )
+  end
+
   # Runs the LLM tool-use loop on persisted session messages.
   #
-  # Unlike {#process}, does not emit {Events::UserMessage} and lets errors
-  # propagate — designed for callers like {AgentRequestJob} that handle
-  # retries and need errors to bubble up.
+  # When a cached first response exists (from {#deliver!}), continues
+  # from that response without a redundant API call. Otherwise makes
+  # a fresh call — used for pending message processing and the standard
+  # path.
   #
-  # @return [String] the agent's response text
+  # Lets errors propagate — designed for callers like {AgentRequestJob}
+  # that handle retries and need errors to bubble up.
+  #
+  # @return [String, nil] the agent's response text, or nil when interrupted
   # @raise [Providers::Anthropic::TransientError] on retryable network/server errors
   # @raise [Providers::Anthropic::AuthenticationError] on auth failures
   def run
@@ -73,15 +104,17 @@ class AgentLoop
     @registry ||= build_tool_registry
 
     messages = @session.messages_for_llm
-    options = {}
+    options = build_llm_options
 
-    unless @session.sub_agent?
-      env_context = EnvironmentProbe.to_prompt(@shell_session.pwd)
-    end
-    prompt = @session.system_prompt(environment_context: env_context)
-    options[:system] = prompt if prompt
+    first_resp = @first_response
+    @first_response = nil
+
+    response = @client.chat_with_tools(
+      messages, registry: @registry, session_id: @session.id,
+      first_response: first_resp, **options
+    )
+    return unless response
 
-    response = @client.chat_with_tools(messages, registry: @registry, session_id: @session.id, **options)
     Events::Bus.emit(Events::AgentMessage.new(content: response, session_id: @session.id))
     response
   end
@@ -94,7 +127,7 @@ class AgentLoop
 
   # Tool classes available to all sessions by default.
   # @return [Array<Class<Tools::Base>>]
-  STANDARD_TOOLS = [Tools::Bash, Tools::Read, Tools::Write, Tools::Edit, Tools::WebGet].freeze
+  STANDARD_TOOLS = [Tools::Bash, Tools::Read, Tools::Write, Tools::Edit, Tools::WebGet, Tools::Think, Tools::Remember].freeze
 
   # Name-to-class mapping for tool restriction validation and registry building.
   # @return [Hash{String => Class<Tools::Base>}]
@@ -102,10 +135,28 @@ class AgentLoop
 
   private
 
+  # @see Session#create_user_event
+  def persist_user_event(content)
+    @session.create_user_event(content)
+  end
+
+  # Assembles LLM options (system prompt, environment context).
+  # @return [Hash] options for {LLM::Client#chat_with_tools}
+  def build_llm_options
+    options = {}
+    unless @session.sub_agent?
+      env_context = EnvironmentProbe.to_prompt(@shell_session.pwd)
+    end
+    prompt = @session.system_prompt(environment_context: env_context)
+    options[:system] = prompt if prompt
+    options
+  end
+
   # Builds the tool registry appropriate for this session type.
   # Main sessions get standard tools + spawn_subagent + spawn_specialist.
-  # Sub-agent sessions get granted standard tools + return_result (no spawning).
-  # Sub-agents cannot spawn further sub-agents (no recursive nesting).
+  # Sub-agents get granted standard tools only (no spawning, no nesting).
+  # Sub-agent results are delivered through natural text messages routed
+  # by {Events::Subscribers::SubagentMessageRouter}.
   # When {Session#granted_tools} is nil, all standard tools are granted.
   # MCP tools from configured servers are registered for all session types.
   #
@@ -116,9 +167,7 @@ class AgentLoop
 
     granted_standard_tools.each { |tool| registry.register(tool) }
 
-    if @session.sub_agent?
-      registry.register(Tools::ReturnResult)
-    else
+    unless @session.sub_agent?
       registry.register(Tools::SpawnSubagent)
       registry.register(Tools::SpawnSpecialist)
       registry.register(Tools::RequestFeature)

data/lib/analytical_brain/runner.rb

@@ -2,67 +2,99 @@
 
 module AnalyticalBrain
   # Orchestrates the analytical brain — a phantom (non-persisted) LLM loop
-  # that observes a main session and performs background maintenance via tools.
+  # that observes a 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.
+  # The brain's capabilities are assembled from independent {Responsibility}
+  # modules, each contributing a prompt section and tools. Which modules are
+  # active depends on the session type:
+  #
+  # * **Parent sessions** — session naming, skill/workflow/goal management
+  # * **Child sessions** — sub-agent nickname assignment, skill/workflow/goal management
+  #
+  # Tools mutate the observed session directly (e.g. renaming it, activating
+  # skills), but no trace of the brain's reasoning is persisted — events are
+  # emitted into a phantom session (session_id: nil).
   #
   # @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.
+    # A composable unit of brain capability: a prompt section + its tools.
+    Responsibility = Data.define(:prompt, :tools)
 
-      ──────────────────────────────
-      SESSION NAMING
-      ──────────────────────────────
-      Call rename_session when the topic becomes clear or shifts.
-      Format: one emoji + 1-3 descriptive words.
+    RESPONSIBILITIES = {
+      session_naming: Responsibility.new(
+        prompt: <<~PROMPT,
+          ──────────────────────────────
+          SESSION NAMING
+          ──────────────────────────────
+          Call rename_session when the topic becomes clear or shifts.
+          Format: one emoji + 1-3 descriptive words.
+        PROMPT
+        tools: [Tools::RenameSession]
+      ),
 
-      ──────────────────────────────
-      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.
+      sub_agent_naming: Responsibility.new(
+        prompt: <<~PROMPT,
+          ──────────────────────────────
+          SUB-AGENT NAMING
+          ──────────────────────────────
+          Call assign_nickname to give this sub-agent a short, memorable nickname.
+          Format: 1-3 lowercase words joined by hyphens (e.g. "loop-sleuth", "api-scout").
+          Evocative of the task, fun, easy to type after @.
+          Generate EXACTLY ONE nickname. If taken, pick another — no numeric suffixes.
+        PROMPT
+        tools: [Tools::AssignNickname]
+      ),
 
-      ──────────────────────────────
-      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.
+      skill_management: Responsibility.new(
+        prompt: <<~PROMPT,
+          ──────────────────────────────
+          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.
+        PROMPT
+        tools: [Tools::ActivateSkill, Tools::DeactivateSkill]
+      ),
 
-      ──────────────────────────────
-      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.
+      workflow_management: Responsibility.new(
+        prompt: <<~PROMPT,
+          ──────────────────────────────
+          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.
+        PROMPT
+        tools: [Tools::ReadWorkflow, Tools::DeactivateWorkflow]
+      ),
 
+      goal_tracking: Responsibility.new(
+        prompt: <<~PROMPT,
+          ──────────────────────────────
+          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.
+        PROMPT
+        tools: [Tools::SetGoal, Tools::UpdateGoal, Tools::FinishGoal]
+      )
+    }.freeze
+
+    BASE_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.
+    PROMPT
+
+    COMPLETION_PROMPT = <<~PROMPT
       ──────────────────────────────
       COMPLETION
       ──────────────────────────────
@@ -70,7 +102,11 @@ module AnalyticalBrain
       If nothing needs changing, call it immediately as your only tool call.
     PROMPT
 
-    # @param session [Session] the main session to observe and maintain
+    # Which responsibilities activate for each session type.
+    PARENT_RESPONSIBILITIES = %i[session_naming skill_management workflow_management goal_tracking].freeze
+    CHILD_RESPONSIBILITIES = %i[sub_agent_naming skill_management workflow_management goal_tracking].freeze
+
+    # @param session [Session] the session to observe and maintain
     # @param client [LLM::Client, nil] injectable LLM client (defaults to fast model)
     def initialize(session, client: nil)
       @session = session
@@ -81,9 +117,9 @@ module AnalyticalBrain
       )
     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.
+    # Runs the analytical brain loop. Builds context from the session's
+    # recent events, calls the LLM with the session-appropriate tool set,
+    # and executes any tool calls against the session.
     #
     # Events emitted during tool execution are not persisted — the phantom
     # session_id (nil) causes the global Persister to skip them.
@@ -116,20 +152,37 @@ module AnalyticalBrain
 
     private
 
+    # @return [Array<Symbol>] responsibility keys for this session type
+    def active_responsibility_keys
+      @session.sub_agent? ? CHILD_RESPONSIBILITIES : PARENT_RESPONSIBILITIES
+    end
+
+    # @return [Array<Responsibility>] active responsibility modules
+    def active_responsibilities
+      active_responsibility_keys.map { |key| RESPONSIBILITIES.fetch(key) }
+    end
+
     # 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 framing differs by session type:
     #
-    # 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.
+    # * **Parent:** "The main session is working on this: [transcript]"
+    # * **Child:** "A sub-agent has been spawned with this task: [transcript]"
     #
     # @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")
+      transcript = events.filter_map { |event| EventDecorator.for(event)&.render("brain") }.join("\n")
+
+      if @session.sub_agent?
+        build_child_message(transcript)
+      else
+        build_parent_message(transcript)
+      end
+    end
+
+    def build_parent_message(transcript)
       content = <<~MSG.strip
         The main session is working on this:
         ```
@@ -141,6 +194,18 @@ module AnalyticalBrain
       [{role: "user", content: content}]
     end
 
+    def build_child_message(transcript)
+      content = <<~MSG.strip
+        A sub-agent has been spawned with this task:
+        ```
+        #{transcript}
+        ```
+
+        Assign a memorable nickname based on the task, activate relevant skills, 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
@@ -151,32 +216,16 @@ module AnalyticalBrain
         .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.
+    # Builds the system prompt from active responsibilities + context sections.
     #
     # @return [String]
     def build_system_prompt
       sections = [
-        SYSTEM_PROMPT,
+        BASE_PROMPT,
+        *active_responsibilities.map(&:prompt),
+        COMPLETION_PROMPT,
         session_state_section,
+        active_siblings_section,
         skills_catalog_section,
         workflows_catalog_section,
         active_goals_section
@@ -199,6 +248,27 @@ module AnalyticalBrain
       SECTION
     end
 
+    # Shows sibling nicknames already in use so the brain avoids collisions
+    # at prompt level (the tool also validates at execution time).
+    #
+    # @return [String, nil] sibling names section, or nil for parent sessions
+    def active_siblings_section
+      return unless @session.sub_agent?
+
+      siblings = @session.parent_session.child_sessions
+        .where.not(id: @session.id)
+        .where.not(name: nil)
+        .pluck(:name)
+      return if siblings.empty?
+
+      <<~SECTION
+        ──────────────────────────────
+        ACTIVE SIBLINGS
+        ──────────────────────────────
+        These nicknames are already taken: #{siblings.join(", ")}
+      SECTION
+    end
+
     # @return [String] available skills list for the analytical brain
     def skills_catalog_section
       catalog = Skills::Registry.instance.catalog
@@ -266,11 +336,16 @@ module AnalyticalBrain
     # @return [Logger] dev-only analytical brain logger
     def log = AnalyticalBrain.logger
 
-    # @return [Tools::Registry] registry with analytical brain tools
+    # @return [Tools::Registry] registry with tools from active responsibilities
     def build_registry
       registry = ::Tools::Registry.new(context: {main_session: @session})
-      TOOLS.each { |tool| registry.register(tool) }
+      active_tools.each { |tool| registry.register(tool) }
       registry
     end
+
+    # @return [Array<Class<Tools::Base>>] tools from all active responsibilities + completion
+    def active_tools
+      active_responsibilities.flat_map(&:tools) + [Tools::EverythingIsReady]
+    end
   end
 end

data/lib/analytical_brain/tools/assign_nickname.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module AnalyticalBrain
+  module Tools
+    # Assigns a static nickname to a sub-agent session.
+    # Operates on the session passed through the registry context.
+    #
+    # Nicknames must be unique among active siblings — the tool returns
+    # an error on collision so the LLM can pick another name naturally,
+    # without programmatic suffixes.
+    #
+    # @see AnalyticalBrain::Runner — invokes this tool for child sessions
+    class AssignNickname < ::Tools::Base
+      # Lowercase hyphenated words: "loop-sleuth", "api-scout", "test-fixer"
+      NICKNAME_PATTERN = /\A[a-z][a-z0-9]*(-[a-z0-9]+)*\z/
+      MAX_LENGTH = 30
+
+      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.input_schema
+        {
+          type: "object",
+          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 @."
+            }
+          },
+          required: %w[nickname]
+        }
+      end
+
+      # @param main_session [Session] the sub-agent session to name
+      def initialize(main_session:, **)
+        @session = main_session
+      end
+
+      # @param input [Hash<String, Object>] with "nickname" key
+      # @return [String] confirmation message
+      # @return [Hash] with :error key on validation failure
+      def execute(input)
+        nickname = input["nickname"].to_s.strip.downcase
+
+        error = validate(nickname)
+        return error if error
+
+        @session.update!(name: nickname)
+        "Nickname set to @#{nickname}"
+      end
+
+      private
+
+      def validate(nickname)
+        return {error: "Nickname cannot be blank"} if nickname.empty?
+        return {error: "Invalid format: use 1-3 lowercase words joined by hyphens"} unless nickname.match?(NICKNAME_PATTERN)
+        return {error: "Nickname too long (max #{MAX_LENGTH} chars)"} if nickname.length > MAX_LENGTH
+
+        if sibling_nickname_taken?(nickname)
+          {error: "Nickname '#{nickname}' is already taken by a sibling. Choose another."}
+        end
+      end
+
+      def sibling_nickname_taken?(nickname)
+        return false unless @session.parent_session
+
+        @session.parent_session.child_sessions
+          .where.not(id: @session.id)
+          .exists?(name: nickname)
+      end
+    end
+  end
+end

data/lib/analytical_brain/tools/finish_goal.rb

@@ -51,11 +51,16 @@ module AnalyticalBrain
         id = goal.id
         return {error: "Goal already completed: #{goal.description} (id: #{id})"} if goal.completed?
 
+        released = 0
         Goal.transaction do
           goal.update!(status: "completed", completed_at: Time.current)
           goal.cascade_completion! if goal.root?
+          released = goal.release_orphaned_pins!
         end
-        "Goal completed: #{goal.description} (id: #{id})"
+
+        msg = "Goal completed: #{goal.description} (id: #{id})"
+        msg += " (released #{released} orphaned pins)" if released > 0
+        msg
       end
     end
   end

data/lib/anima/cli.rb

@@ -20,6 +20,38 @@ module Anima
       Installer.new.run
     end
 
+    desc "update", "Upgrade gem and migrate config"
+    option :migrate_only, type: :boolean, default: false, desc: "Skip gem upgrade, only migrate config"
+    def update
+      unless options[:migrate_only]
+        say "Upgrading anima-core gem..."
+        unless system("gem", "update", "anima-core")
+          say "Gem update failed.", :red
+          exit 1
+        end
+
+        # Re-exec with the updated gem so migration uses the new template.
+        exec(File.join(Gem.bindir, "anima"), "update", "--migrate-only")
+      end
+
+      say "Migrating configuration..."
+      require_relative "config_migrator"
+      result = Anima::ConfigMigrator.new.run
+
+      case result.status
+      when :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
+        say "Config updated. Changes take effect immediately — no restart needed."
+      end
+    end
+
     # Start the Anima brain server (Puma + Solid Queue) via Foreman.
     # Environment precedence: -e flag > RAILS_ENV env var > "development".
     # Requires prior installation (~/.anima must exist).
@@ -46,6 +78,7 @@ module Anima
 
     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"
     def tui
       require "ratatui_ruby"
       require_relative "../tui/app"
@@ -57,7 +90,7 @@ module Anima
       cable_client = TUI::CableClient.new(host: host)
       cable_client.connect
 
-      TUI::App.new(cable_client: cable_client).run
+      TUI::App.new(cable_client: cable_client, debug: options[:debug]).run
     end
 
     desc "version", "Show version"