anima-core 1.3.0 → 1.5.0

data/app/jobs/agent_request_job.rb

@@ -1,199 +0,0 @@
-# frozen_string_literal: true
-
-# Executes an LLM agent loop as a background job with retry logic
-# for transient failures (network errors, rate limits, server errors).
-#
-# Supports two modes:
-#
-# **Immediate Persist (message_id provided):** The user message was already
-# persisted and broadcast by the caller (e.g. {SessionChannel#speak}).
-# The job verifies LLM delivery — if the first API call fails, the
-# message is deleted and a {Events::BounceBack} is emitted so clients
-# can restore the text to the input field.
-#
-# **Standard (no message_id):** Processes already-persisted messages (e.g.
-# after pending message promotion). Uses ActiveJob retry/discard for
-# error handling.
-#
-# @example Immediate Persist — message already saved by SessionChannel
-#   AgentRequestJob.perform_later(session.id, message_id: 42)
-#
-# @example Standard — pending message processing
-#   AgentRequestJob.perform_later(session.id)
-class AgentRequestJob < ApplicationJob
-  queue_as :default
-
-  # ActionCable action signaling clients to prompt for an API token.
-  AUTH_REQUIRED_ACTION = "authentication_required"
-
-  # Standard path only — immediate persist handles its own errors.
-  retry_on Providers::Anthropic::TransientError,
-    wait: :polynomially_longer, attempts: 5 do |job, error|
-    Events::Bus.emit(Events::SystemMessage.new(
-      content: "Failed after multiple retries: #{error.message}",
-      session_id: job.arguments.first
-    ))
-  end
-
-  discard_on ActiveRecord::RecordNotFound
-  discard_on Providers::Anthropic::AuthenticationError do |job, error|
-    session_id = job.arguments.first
-    Events::Bus.emit(Events::SystemMessage.new(
-      content: "Authentication failed: #{error.message}",
-      session_id: session_id
-    ))
-    ActionCable.server.broadcast(
-      "session_#{session_id}",
-      {"action" => AUTH_REQUIRED_ACTION, "message" => error.message}
-    )
-  end
-
-  # @param session_id [Integer] ID of the session to process
-  # @param message_id [Integer, nil] ID of a pre-persisted user message (triggers delivery verification)
-  def perform(session_id, message_id: nil)
-    session = Session.find(session_id)
-
-    # Atomic: only one job processes a session at a time.
-    return unless claim_processing(session_id)
-
-    run_analytical_brain_blocking(session)
-
-    agent_loop = AgentLoop.new(session: session)
-
-    if message_id
-      deliver_persisted_message(session, message_id, agent_loop)
-    else
-      agent_loop.run
-    end
-
-    # Process any pending messages queued while we were busy.
-    loop do
-      promoted = session.promote_pending_messages!
-      break if promoted == 0
-      agent_loop.run
-    end
-
-    session.schedule_analytical_brain!
-  ensure
-    release_processing(session_id)
-    clear_interrupt(session_id)
-    agent_loop&.finalize
-  end
-
-  private
-
-  # Verifies LLM delivery for a pre-persisted user message.
-  #
-  # The message was already created and broadcast by the caller, so
-  # the user sees their message immediately. This method makes the
-  # first LLM API call — if it fails, the message is deleted and a
-  # {Events::BounceBack} notifies clients to remove the phantom
-  # message and restore the text to the input field. For
-  # {Providers::Anthropic::AuthenticationError}, an additional
-  # +authentication_required+ broadcast prompts the client to show
-  # the token entry dialog.
-  #
-  # Unlike the standard path (which uses +retry_on+ / +discard_on+),
-  # all errors here are caught and swallowed after emitting a
-  # BounceBack — the job completes normally so ActiveJob does not
-  # retry a message the user will re-send manually.
-  #
-  # After successful delivery, continues the agent loop (tool
-  # execution, subsequent API calls).
-  #
-  # @param session [Session] the conversation session
-  # @param message_id [Integer] database ID of the pre-persisted user message
-  # @param agent_loop [AgentLoop] agent loop instance (reused for continuation)
-  def deliver_persisted_message(session, message_id, agent_loop)
-    message = Message.find_by(id: message_id, session_id: session.id)
-    # Message may have been deleted between SessionChannel#speak and job
-    # execution (e.g. user recalled the message). Exit silently — there
-    # is nothing to deliver or bounce back.
-    return unless message
-
-    content = message.payload["content"]
-
-    begin
-      agent_loop.deliver!
-    rescue => error
-      message.destroy!
-      Events::Bus.emit(Events::BounceBack.new(
-        content: content,
-        error: error.message,
-        session_id: session.id,
-        message_id: message_id
-      ))
-      broadcast_auth_required(session.id, error) if error.is_a?(Providers::Anthropic::AuthenticationError)
-      return
-    end
-
-    agent_loop.run
-  end
-
-  def broadcast_auth_required(session_id, error)
-    ActionCable.server.broadcast(
-      "session_#{session_id}",
-      {"action" => AUTH_REQUIRED_ACTION, "message" => error.message}
-    )
-  end
-
-  # Runs the analytical brain synchronously before the main agent loop.
-  # Respects the blocking_on_user_message setting and session guards
-  # (skips sub-agents and sessions with too few messages).
-  def run_analytical_brain_blocking(session)
-    return unless Anima::Settings.analytical_brain_blocking_on_user_message
-    return if session.sub_agent?
-
-    AnalyticalBrain::Runner.new(session).call
-  rescue => error
-    # The analytical brain is best-effort: skill activation enhances the
-    # response but the main agent must still reply even if it fails.
-    msg = "FAILED (blocking) session=#{session.id}: #{error.class}: #{error.message}"
-    Rails.logger.error("Analytical brain #{msg}")
-    AnalyticalBrain.logger.error("#{msg}\n#{error.backtrace&.first(10)&.join("\n")}")
-  end
-
-  # Sets the session's processing flag atomically. Returns true if this
-  # job claimed the lock, false if another job already holds it.
-  # Broadcasts +session_state: llm_generating+ and the state change to
-  # the parent session's HUD.
-  def claim_processing(session_id)
-    claimed = Session.where(id: session_id, processing: false).update_all(processing: true) == 1
-    if claimed
-      session = Session.find_by(id: session_id)
-      session&.broadcast_session_state("llm_generating")
-      session&.broadcast_children_update_to_parent
-    end
-    claimed
-  end
-
-  # Clears the processing flag so the session can accept new jobs.
-  # Broadcasts +session_state: idle+ to the session stream (replaces
-  # the old +processing_stopped+ action) and +children_updated+ to the
-  # parent session's HUD.
-  def release_processing(session_id)
-    Session.where(id: session_id).update_all(processing: false)
-    session = Session.find_by(id: session_id)
-    session&.broadcast_session_state("idle")
-    session&.broadcast_children_update_to_parent
-  end
-
-  # Safety-net clearing of the interrupt flag.
-  def clear_interrupt(session_id)
-    Session.where(id: session_id, interrupt_requested: true).update_all(interrupt_requested: false)
-  end
-
-  # Emits a system message before each retry so the user sees
-  # "retrying..." instead of nothing.
-  def retry_job(options = {})
-    error = options[:error]
-    wait = options[:wait]
-
-    Events::Bus.emit(Events::SystemMessage.new(
-      content: "#{error.message} — retrying in #{wait.to_i}s...",
-      session_id: arguments.first
-    ))
-
-    super
-  end
-end

data/app/jobs/analytical_brain_job.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-# Runs the analytical brain — a phantom LLM loop that observes the main
-# session and performs background maintenance (currently: session naming).
-#
-# Replaces {GenerateSessionNameJob} with a tool-based architecture that
-# future tickets will expand with skill activation, goal tracking, etc.
-#
-# Scheduling guards live in {Session#schedule_analytical_brain!} — this
-# job always runs when called.
-#
-# @example
-#   AnalyticalBrainJob.perform_later(session.id)
-class AnalyticalBrainJob < ApplicationJob
-  queue_as :default
-
-  retry_on Providers::Anthropic::TransientError,
-    wait: :polynomially_longer, attempts: 3
-
-  discard_on ActiveRecord::RecordNotFound
-  discard_on Providers::Anthropic::AuthenticationError
-
-  # @param session_id [Integer] the main Session to analyze
-  def perform(session_id)
-    brain_log = AnalyticalBrain.logger
-    session = Session.find(session_id)
-    brain_log.info("async job started for session=#{session_id}")
-    AnalyticalBrain::Runner.new(session).call
-  rescue => error
-    brain_log.error("FAILED (async) session=#{session_id}: #{error.class}: #{error.message}")
-    raise
-  end
-end

data/app/jobs/count_message_tokens_job.rb

@@ -1,39 +0,0 @@
-# frozen_string_literal: true
-
-# Counts tokens in a message's payload via the Anthropic API and
-# caches the result on the message record. Enqueued automatically
-# after each LLM message is created.
-class CountMessageTokensJob < ApplicationJob
-  queue_as :default
-
-  retry_on Providers::Anthropic::Error, wait: :polynomially_longer, attempts: 3
-  discard_on ActiveRecord::RecordNotFound
-
-  # @param message_id [Integer] the Message record to count tokens for
-  def perform(message_id)
-    message = Message.find(message_id)
-    return if already_counted?(message)
-
-    provider = Providers::Anthropic.new
-    api_messages = [{role: message.api_role, content: message.payload["content"].to_s}]
-
-    token_count = provider.count_tokens(
-      model: Anima::Settings.model,
-      messages: api_messages
-    )
-
-    # Guard against parallel jobs: reload and re-check before writing.
-    # Uses update! (not update_all) so {Message::Broadcasting} after_update_commit
-    # broadcasts the updated token count to connected clients.
-    message.reload
-    return if already_counted?(message)
-
-    message.update!(token_count: token_count)
-  end
-
-  private
-
-  def already_counted?(message)
-    message.token_count > 0
-  end
-end

data/app/jobs/passive_recall_job.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-# Runs passive recall after goal updates — searches message history for
-# context relevant to active goals and caches results on the session
-# for viewport injection.
-#
-# Idempotent: multiple enqueues for the same session safely overwrite
-# each other's results — last one wins.
-#
-# @example
-#   PassiveRecallJob.perform_later(session.id)
-class PassiveRecallJob < ApplicationJob
-  queue_as :default
-
-  discard_on ActiveRecord::RecordNotFound
-
-  # @param session_id [Integer]
-  def perform(session_id)
-    session = Session.find(session_id)
-    results = Mneme::PassiveRecall.new(session).call
-
-    if results.any?
-      session.update_column(:recalled_message_ids, results.map(&:message_id))
-      Mneme.logger.info("session=#{session_id} — passive recall found #{results.size} memories")
-    elsif session.recalled_message_ids.present?
-      session.update_column(:recalled_message_ids, [])
-    end
-  end
-end

data/app/models/concerns/message/broadcasting.rb

@@ -1,85 +0,0 @@
-# frozen_string_literal: true
-
-# Broadcasts Message records to connected WebSocket clients via ActionCable.
-# Follows the Turbo Streams pattern: messages are broadcast on both create
-# and update, with an action type so clients can distinguish append from
-# replace operations.
-#
-# Each broadcast includes the Message's database ID, enabling clients to
-# maintain an ID-indexed store for efficient in-place updates (e.g. when
-# token counts arrive asynchronously from {CountMessageTokensJob}).
-#
-# When a new message pushes old messages out of the LLM's context window,
-# the broadcast includes `evicted_message_ids` so clients can remove
-# phantom messages that the agent no longer knows about.
-#
-# @example Create broadcast payload
-#   {
-#     "type" => "user_message", "content" => "hello", ...,
-#     "id" => 42, "action" => "create",
-#     "rendered" => { "basic" => { "role" => "user", "content" => "hello" } }
-#   }
-#
-# @example Broadcast with viewport evictions
-#   {
-#     "type" => "agent_message", "content" => "...", ...,
-#     "id" => 99, "action" => "create",
-#     "evicted_message_ids" => [101, 102, 103]
-#   }
-#
-# @example Update broadcast payload (e.g. token count arrives)
-#   {
-#     "type" => "user_message", "content" => "hello", ...,
-#     "id" => 42, "action" => "update",
-#     "rendered" => { "debug" => { "role" => "user", "content" => "hello", "tokens" => 15 } }
-#   }
-module Message::Broadcasting
-  extend ActiveSupport::Concern
-
-  ACTION_CREATE = "create"
-  ACTION_UPDATE = "update"
-
-  included do
-    after_create_commit :broadcast_create
-    after_update_commit :broadcast_update
-  end
-
-  private
-
-  def broadcast_create
-    broadcast_message(action: ACTION_CREATE)
-  end
-
-  def broadcast_update
-    broadcast_message(action: ACTION_UPDATE)
-  end
-
-  # Decorates the message for the session's current view mode and broadcasts
-  # the payload to the session's ActionCable stream. Includes viewport
-  # eviction metadata so clients can remove messages the LLM has forgotten.
-  #
-  # @param action [String] ACTION_CREATE or ACTION_UPDATE — tells clients how to handle the message
-  def broadcast_message(action:)
-    return unless session_id
-
-    session = Session.find_by(id: session_id)
-    return unless session
-
-    mode = session.view_mode
-    decorator = MessageDecorator.for(self)
-    broadcast_payload = payload.merge("id" => id, "action" => action)
-
-    if decorator
-      broadcast_payload["rendered"] = {mode => decorator.render(mode)}
-    end
-
-    evicted_ids = session.recalculate_viewport!
-    broadcast_payload["evicted_message_ids"] = evicted_ids if evicted_ids.any?
-
-    # The nil? branch fires on every broadcast until boundary initializes, but
-    # schedule_mneme! returns early after setting the boundary — cost is one DB read + write.
-    session.schedule_mneme! if evicted_ids.any? || session.mneme_boundary_message_id.nil?
-
-    ActionCable.server.broadcast("session_#{session_id}", broadcast_payload)
-  end
-end

data/config/initializers/fts5_schema_dump.rb

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

data/lib/agent_loop.rb

@@ -1,186 +0,0 @@
-# frozen_string_literal: true
-
-# Orchestrates the LLM agent loop: accepts user input, runs the tool-use
-# cycle via {LLM::Client}, and emits events through {Events::Bus}.
-#
-# Extracted from {TUI::Screens::Chat} so the same agent logic can run from
-# the TUI, a background job, or an Action Cable channel.
-#
-# @note Not thread-safe. Callers must serialize concurrent access
-#   (e.g. {AgentRequestJob} uses session-level processing locks).
-#
-# @example Basic usage
-#   loop = AgentLoop.new(session: session)
-#   loop.run
-#   loop.finalize
-#
-# @example With dependency injection (testing)
-#   loop = AgentLoop.new(session: session, client: mock_client, registry: mock_registry)
-#   loop.run
-class AgentLoop
-  # @return [Session] the conversation session this loop operates on
-  attr_reader :session
-
-  # @param session [Session] the conversation session
-  # @param shell_session [ShellSession, nil] injectable persistent shell;
-  #   created automatically if not provided
-  # @param client [LLM::Client, nil] injectable LLM client;
-  #   created lazily on first {#run} call if not provided
-  # @param registry [Tools::Registry, nil] injectable tool registry;
-  #   built lazily on first {#run} call if not provided
-  def initialize(session:, shell_session: nil, client: nil, registry: nil)
-    @session = session
-    @shell_session = shell_session || ShellSession.new(session_id: session.id)
-    @client = client
-    @registry = registry
-  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.
-  #
-  # 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.
-  #
-  # 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
-    @client ||= LLM::Client.new
-    @registry ||= build_tool_registry
-
-    messages = @session.messages_for_llm
-    options = build_llm_options
-
-    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
-
-    Events::Bus.emit(Events::AgentMessage.new(content: response, session_id: @session.id))
-    response
-  end
-
-  # Clean up the underlying {ShellSession} PTY and resources.
-  # Safe to call multiple times — subsequent calls are no-ops.
-  def finalize
-    @shell_session&.finalize
-  end
-
-  # 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, Tools::Think, Tools::Remember, Tools::Recall].freeze
-
-  # Tools that bypass {Session#granted_tools} filtering.
-  # The agent's reasoning depends on these regardless of task scope.
-  # @return [Array<Class<Tools::Base>>]
-  ALWAYS_GRANTED_TOOLS = [Tools::Think].freeze
-
-  # Name-to-class mapping for tool restriction validation and registry building.
-  # @return [Hash{String => Class<Tools::Base>}]
-  STANDARD_TOOLS_BY_NAME = STANDARD_TOOLS.index_by(&:tool_name).freeze
-
-  private
-
-  # Assembles LLM options (system prompt, environment context).
-  # Broadcasts the full debug context (system prompt + tool schemas)
-  # to debug-mode TUI clients on every LLM request.
-  # @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
-    @session.broadcast_debug_context(system: prompt, tools: @registry&.schemas)
-    options
-  end
-
-  # Builds the tool registry appropriate for this session type.
-  # Main sessions get standard tools + spawn_subagent + spawn_specialist.
-  # 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.
-  #
-  # @return [Tools::Registry] registry with available tools
-  def build_tool_registry
-    context = {shell_session: @shell_session, session: @session}
-    registry = Tools::Registry.new(context: context)
-
-    granted_standard_tools.each { |tool| registry.register(tool) }
-
-    if @session.sub_agent?
-      registry.register(Tools::MarkGoalCompleted)
-    else
-      registry.register(Tools::SpawnSubagent)
-      registry.register(Tools::SpawnSpecialist)
-      registry.register(Tools::OpenIssue)
-    end
-
-    register_mcp_tools(registry)
-
-    registry
-  end
-
-  # Loads tools from configured MCP servers and adds them to the registry.
-  # Warnings are emitted as system messages — visible to both the user
-  # (in verbose mode) and the LLM (via CONTEXT_TYPES) so the agent can
-  # explain config issues instead of guessing.
-  #
-  # @param registry [Tools::Registry] the registry to add MCP tools to
-  # @return [void]
-  def register_mcp_tools(registry)
-    warnings = Mcp::ClientManager.new.register_tools(registry)
-    warnings.each do |message|
-      Events::Bus.emit(Events::SystemMessage.new(content: message, session_id: @session.id))
-    end
-  end
-
-  # Standard tools available to this session.
-  # Returns all when {Session#granted_tools} is nil (no restriction).
-  # Returns only matching tools when granted_tools is an array,
-  # always including {ALWAYS_GRANTED_TOOLS}.
-  #
-  # @return [Array<Class<Tools::Base>>] tool classes to register
-  def granted_standard_tools
-    granted = @session.granted_tools
-    return STANDARD_TOOLS unless granted
-
-    explicitly_granted = granted.filter_map { |name| STANDARD_TOOLS_BY_NAME[name] }
-    (ALWAYS_GRANTED_TOOLS + explicitly_granted).uniq
-  end
-end

data/lib/analytical_brain/tools/deactivate_skill.rb

@@ -1,39 +0,0 @@
-# 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 = "Remove domain knowledge that is no longer relevant."
-
-      def self.input_schema
-        {
-          type: "object",
-          properties: {
-            skill_name: {type: "string"}
-          },
-          required: %w[skill_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 "skill_name" key
-      # @return [String] confirmation message
-      # @return [Hash] with :error key on validation failure
-      def execute(input)
-        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)
-        "Deactivated skill: #{skill_name}"
-      end
-    end
-  end
-end

data/lib/analytical_brain/tools/deactivate_workflow.rb

@@ -1,34 +0,0 @@
-# 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