anima-core 1.4.0 → 1.5.0

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

@@ -1,86 +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)
-    broadcast_payload["api_metrics"] = api_metrics if api_metrics.present?
-
-    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/lib/agent_loop.rb

@@ -1,215 +0,0 @@
-# frozen_string_literal: true
-
-require "shellwords"
-
-# 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)
-    restore_initial_cwd
-    @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 ||= build_client
-    @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,
-      include_metrics: true,
-      **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 ||= build_client
-    @registry ||= build_tool_registry
-
-    messages = @session.messages_for_llm
-    options = build_llm_options
-
-    first_resp = @first_response
-    @first_response = nil
-
-    between_rounds = -> { @session.promote_pending_messages! }
-
-    result = @client.chat_with_tools(
-      messages, registry: @registry, session_id: @session.id,
-      first_response: first_resp, between_rounds: between_rounds, **options
-    )
-    return unless result
-
-    Events::Bus.emit(Events::AgentMessage.new(
-      content: result[:text],
-      session_id: @session.id,
-      api_metrics: result[:api_metrics]
-    ))
-    result[:text]
-  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
-
-  # Restores the working directory inherited from the parent session.
-  # Sub-agents store the parent's CWD at spawn time so their shell starts
-  # in the same directory the parent was working in.
-  # @return [void]
-  def restore_initial_cwd
-    cwd = @session.initial_cwd
-    return unless cwd.present? && File.directory?(cwd)
-
-    @shell_session.run("cd #{Shellwords.shellescape(cwd)}")
-  end
-
-  # Builds the LLM client with the appropriate model for this session type.
-  # Sub-agents use a separate (typically cheaper) model from Settings.
-  # @return [LLM::Client]
-  def build_client
-    if @session.sub_agent?
-      LLM::Client.new(model: Anima::Settings.subagent_model)
-    else
-      LLM::Client.new
-    end
-  end
-
-  # Assembles LLM options (system prompt).
-  # 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 = {}
-    prompt = @session.system_prompt
-    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,40 +0,0 @@
-# frozen_string_literal: true
-
-module AnalyticalBrain
-  module Tools
-    # Deactivates a domain knowledge skill on the main session.
-    # The skill's recalled message stays in the conversation and
-    # evicts naturally from the sliding window.
-    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,35 +0,0 @@
-# frozen_string_literal: true
-
-module AnalyticalBrain
-  module Tools
-    # Deactivates the current workflow on the main session.
-    # The workflow's recalled message stays in the conversation and
-    # evicts naturally from the sliding window.
-    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/events/agent_message.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-module Events
-  class AgentMessage < Base
-    TYPE = "agent_message"
-
-    attr_reader :api_metrics
-
-    # @param content [String] assistant response text
-    # @param session_id [Integer, String] session identifier
-    # @param api_metrics [Hash, nil] rate limits and usage from API response
-    def initialize(content:, session_id: nil, api_metrics: nil)
-      super(content: content, session_id: session_id)
-      @api_metrics = api_metrics
-    end
-
-    def type
-      TYPE
-    end
-
-    def to_h
-      super.merge(api_metrics: api_metrics)
-    end
-  end
-end

data/lib/events/subscribers/message_collector.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-module Events
-  module Subscribers
-    # Collects chat-displayable events in-memory for the current session.
-    # Provides the message list that the TUI renders and the LLM client consumes.
-    #
-    # Only user_message and agent_message events are collected — system_message,
-    # tool_call, and tool_response are internal and not part of the chat display.
-    #
-    # @example
-    #   collector = Events::Subscribers::MessageCollector.new
-    #   Events::Bus.subscribe(collector)
-    #   collector.messages # => [{role: "user", content: "hi"}, ...]
-    class MessageCollector
-      include Events::Subscriber
-
-      DISPLAYABLE_TYPES = %w[user_message agent_message].freeze
-
-      # Maps event types to LLM-compatible role identifiers
-      ROLE_MAP = {
-        "user_message" => "user",
-        "agent_message" => "assistant"
-      }.freeze
-
-      def initialize
-        @messages = []
-        @mutex = Mutex.new
-      end
-
-      # @return [Array<Hash>] thread-safe copy of collected messages
-      def messages
-        @mutex.synchronize { @messages.dup }
-      end
-
-      # Receives a Rails.event notification hash.
-      # @param event [Hash] with :payload containing :type and :content keys
-      def emit(event)
-        type = event.dig(:payload, :type)
-        return unless DISPLAYABLE_TYPES.include?(type)
-
-        content = event.dig(:payload, :content)
-        return if content.nil?
-
-        @mutex.synchronize do
-          @messages << {
-            role: ROLE_MAP.fetch(type),
-            content: content
-          }
-        end
-      end
-
-      # Directly push a pre-built message hash (used for loading persisted events).
-      # @param message [Hash] with :role and :content keys
-      def messages_push(message)
-        @mutex.synchronize { @messages << message }
-      end
-
-      def clear
-        @mutex.synchronize { @messages = [] }
-      end
-    end
-  end
-end

data/lib/events/tool_call.rb

@@ -1,31 +0,0 @@
-# frozen_string_literal: true
-
-module Events
-  class ToolCall < Base
-    TYPE = "tool_call"
-
-    attr_reader :tool_name, :tool_input, :tool_use_id, :timeout
-
-    # @param content [String] human-readable description of the tool call
-    # @param tool_name [String] registered tool name (e.g. "web_get")
-    # @param tool_input [Hash] arguments passed to the tool
-    # @param tool_use_id [String] Anthropic-assigned ID for correlating call/result
-    # @param timeout [Integer] maximum seconds before the call is considered orphaned
-    # @param session_id [String, nil] optional session identifier
-    def initialize(content:, tool_name:, tool_input: {}, tool_use_id: nil, timeout: nil, session_id: nil)
-      super(content: content, session_id: session_id)
-      @tool_name = tool_name
-      @tool_input = tool_input
-      @tool_use_id = tool_use_id
-      @timeout = timeout
-    end
-
-    def type
-      TYPE
-    end
-
-    def to_h
-      super.merge(tool_name: tool_name, tool_input: tool_input, tool_use_id: tool_use_id, timeout: timeout)
-    end
-  end
-end

data/lib/events/tool_response.rb

@@ -1,33 +0,0 @@
-# frozen_string_literal: true
-
-module Events
-  class ToolResponse < Base
-    TYPE = "tool_response"
-
-    attr_reader :tool_name, :success, :tool_use_id
-
-    # @param content [String] tool execution output
-    # @param tool_name [String] registered tool name
-    # @param success [Boolean] whether the tool executed successfully
-    # @param tool_use_id [String, nil] Anthropic-assigned ID for correlating call/result
-    # @param session_id [String, nil] optional session identifier
-    def initialize(content:, tool_name:, success: true, tool_use_id: nil, session_id: nil)
-      super(content: content, session_id: session_id)
-      @tool_name = tool_name
-      @success = success
-      @tool_use_id = tool_use_id
-    end
-
-    def type
-      TYPE
-    end
-
-    def success?
-      @success
-    end
-
-    def to_h
-      super.merge(tool_name: tool_name, success: success, tool_use_id: tool_use_id)
-    end
-  end
-end