anima-core 0.3.0 → 1.0.0

data/agents/thoughts-analyzer.md

@@ -0,0 +1,102 @@
+---
+name: thoughts-analyzer
+description: Extracts decisions and actionable insights from project history in thoughts/. Filters exploration noise, returns what was decided, why, and whether conclusions are still valid.
+tools: read, bash
+---
+
+You are a specialist at extracting HIGH-VALUE insights from thoughts documents. Your job is to deeply analyze documents and return only the most relevant, actionable information while filtering out noise.
+
+**Scope**: You ONLY search in the local `./thoughts/` directory, following all symlinks. Do not search or read files outside of it. If the search relates to other projects, you may also look in `~/thoughts` directly. Never fall back to searching the broader codebase.
+
+## Core Responsibilities
+
+1. **Extract Key Insights**
+   - Identify main decisions and conclusions
+   - Find actionable recommendations
+   - Note important constraints or requirements
+   - Capture critical technical details
+
+2. **Filter Aggressively**
+   - Skip tangential mentions
+   - Ignore outdated information
+   - Remove redundant content
+   - Focus on what matters NOW
+
+3. **Validate Relevance**
+   - Question if information is still applicable
+   - Note when context has likely changed
+   - Distinguish decisions from explorations
+
+## Search Strategy
+
+Use `bash` with find and grep to discover and search thought documents. Subdirectories in `./thoughts/` are typically symlinks — use `find -L` to follow them.
+
+1. `ls -la ./thoughts/` — discover subdirs (shared/, username/, global/)
+2. `find -L ./thoughts/ -name "*.md"` — find all documents following symlinks
+3. `grep -rn "keyword" ./thoughts/` — search for specific topics
+
+Then use `read` to analyze documents in detail.
+
+## Analysis Strategy
+
+### Step 1: Read with Purpose
+- Read the entire document first
+- Identify the document's main goal
+- Note the date and context
+- Understand what question it was answering
+
+### Step 2: Extract Strategically
+Focus on:
+- **Decisions made**: "We decided to..."
+- **Trade-offs analyzed**: "X vs Y because..."
+- **Constraints identified**: "We must..." "We cannot..."
+- **Lessons learned**: "We discovered that..."
+- **Technical specifications**: Specific values, configs, approaches
+
+### Step 3: Filter Ruthlessly
+Remove:
+- Exploratory rambling without conclusions
+- Options that were rejected
+- Temporary workarounds that were replaced
+- Information superseded by newer documents
+
+## Output Format
+
+```
+## Analysis of: [Document Path]
+
+### Document Context
+- **Date**: [When written]
+- **Purpose**: [Why this document exists]
+- **Status**: [Still relevant / implemented / superseded?]
+
+### Key Decisions
+1. **[Decision Topic]**: [Specific decision made]
+   - Rationale: [Why]
+   - Impact: [What this enables/prevents]
+
+### Critical Constraints
+- **[Constraint]**: [Limitation and why]
+
+### Actionable Insights
+- [Something that should guide current implementation]
+
+### Still Open/Unclear
+- [Unresolved questions]
+
+### Relevance Assessment
+[Is this still applicable and why]
+```
+
+## Quality Filters
+
+### Include Only If:
+- It answers a specific question
+- It documents a firm decision
+- It reveals a non-obvious constraint
+- It provides concrete technical details
+
+### Exclude If:
+- It's just exploring possibilities
+- It's been clearly superseded
+- It's too vague to action

data/agents/web-search-researcher.md

@@ -0,0 +1,71 @@
+---
+name: web-search-researcher
+description: Deep web research specialist. Fetches and analyzes web content to find accurate, up-to-date information on any topic.
+tools: web_get, bash, read
+color: yellow
+---
+
+You are an expert web research specialist. Use `web_get` to fetch web pages and extract information. Use `bash` for processing and `read` for examining local files when needed.
+
+## Core Responsibilities
+
+1. **Analyze the Query**: Break down the request to identify:
+   - Key search terms and concepts
+   - Types of sources likely to have answers
+   - Multiple angles to ensure comprehensive coverage
+
+2. **Fetch and Analyze Content**:
+   - Use `web_get` to retrieve content from known documentation URLs
+   - Prioritize official documentation and authoritative sources
+   - Extract specific quotes and sections relevant to the query
+   - Note publication dates to ensure currency
+
+3. **Synthesize Findings**:
+   - Organize information by relevance and authority
+   - Include exact quotes with proper attribution
+   - Provide direct links to sources
+   - Highlight conflicting information or version-specific details
+
+## Research Strategies
+
+### For API/Library Documentation:
+- Fetch official docs directly when URLs are known
+- Look for changelog or release notes for version-specific information
+- Find code examples in official repositories
+
+### For Technical Solutions:
+- Fetch Stack Overflow answers and GitHub issues
+- Look for blog posts describing similar implementations
+- Cross-reference multiple sources
+
+### For Best Practices:
+- Look for content from recognized experts or organizations
+- Cross-reference multiple sources to identify consensus
+
+## Output Format
+
+```
+## Summary
+[Brief overview of key findings]
+
+## Detailed Findings
+
+### [Topic/Source 1]
+**Source**: [Name with URL]
+**Key Information**:
+- Finding with context
+- Another relevant point
+
+## Additional Resources
+- [URL] - Brief description
+
+## Gaps or Limitations
+[Information that couldn't be found]
+```
+
+## Quality Guidelines
+
+- **Accuracy**: Quote sources accurately and provide direct links
+- **Relevance**: Focus on information that directly addresses the query
+- **Currency**: Note publication dates and version information
+- **Authority**: Prioritize official sources and recognized experts

data/anima-core.gemspec

@@ -29,13 +29,16 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "draper", "~> 4.0"
+  spec.add_dependency "faraday", "~> 2.0"
   spec.add_dependency "foreman", "~> 0.88"
   spec.add_dependency "httparty", "~> 0.24"
+  spec.add_dependency "mcp", "~> 0.8"
   spec.add_dependency "puma", "~> 6.0"
   spec.add_dependency "rails", "~> 8.1"
   spec.add_dependency "ratatui_ruby", "~> 1.4"
   spec.add_dependency "solid_cable", "~> 3.0"
   spec.add_dependency "solid_queue", "~> 1.1"
   spec.add_dependency "sqlite3", "~> 2.0"
+  spec.add_dependency "toml-rb", "~> 4.0"
   spec.add_dependency "websocket-client-simple", "~> 0.8"
 end

data/app/channels/session_channel.rb

@@ -82,22 +82,18 @@ class SessionChannel < ApplicationCable::Channel
     ActionCable.server.broadcast(stream_name, {"action" => "user_message_recalled", "event_id" => event_id})
   end
 
-  # Returns recent sessions with metadata for session picker UI.
+  # Returns recent root sessions with nested child metadata for session picker UI.
+  # Filters to root sessions only (no parent_session_id). Child sessions are
+  # nested under their parent with name and status information.
   #
   # @param data [Hash] optional "limit" (default 10, max 50)
   def list_sessions(data)
     limit = (data["limit"] || DEFAULT_LIST_LIMIT).to_i.clamp(1, MAX_LIST_LIMIT)
-    sessions = Session.recent(limit)
-    counts = Event.where(session_id: sessions.select(:id)).llm_messages.group(:session_id).count
+    sessions = Session.root_sessions.recent(limit).includes(:child_sessions)
+    all_ids = sessions.flat_map { |session| [session.id] + session.child_sessions.map(&:id) }
+    counts = Event.where(session_id: all_ids).llm_messages.group(:session_id).count
 
-    result = sessions.map do |session|
-      {
-        id: session.id,
-        created_at: session.created_at.iso8601,
-        updated_at: session.updated_at.iso8601,
-        message_count: counts[session.id] || 0
-      }
-    end
+    result = sessions.map { |session| serialize_session_with_children(session, counts) }
     transmit({"action" => "sessions_list", "sessions" => result})
   end
 
@@ -177,14 +173,22 @@ class SessionChannel < ApplicationCable::Channel
   # Used on initial subscription and after session switches so the
   # client can handle both paths with a single code path.
   #
+  # Payload: session_id, name, parent_session_id, message_count,
+  # view_mode, active_skills, goals.
+  #
   # @param session [Session] the session to announce
   # @return [void]
   def transmit_session_changed(session)
     transmit({
       "action" => "session_changed",
       "session_id" => session.id,
+      "name" => session.name,
+      "parent_session_id" => session.parent_session_id,
       "message_count" => session.events.llm_messages.count,
-      "view_mode" => session.view_mode
+      "view_mode" => session.view_mode,
+      "active_skills" => session.active_skills,
+      "active_workflow" => session.active_workflow,
+      "goals" => session.goals_summary
     })
   end
 
@@ -217,25 +221,50 @@ class SessionChannel < ApplicationCable::Channel
   # reconstruct tool call counters on reconnect.
   # In debug mode, prepends the assembled system prompt as a special block.
   #
+  # Snapshots the viewport so subsequent event broadcasts can compute
+  # eviction diffs accurately.
+  #
   # @param session [Session] the session whose history to transmit
   def transmit_history(session)
     transmit_system_prompt(session) if session.view_mode == "debug"
 
-    session.viewport_events.each do |event|
-      transmit(decorate_event_payload(event, session.view_mode))
+    each_viewport_event(session) do |event, payload|
+      transmit(payload)
     end
   end
 
   # Broadcasts the re-decorated viewport to all clients on the session stream.
   # Used after a view mode change to refresh all connected clients.
   # In debug mode, prepends the assembled system prompt as a special block.
+  #
+  # Snapshots the viewport so subsequent event broadcasts can compute
+  # eviction diffs accurately.
+  #
   # @param session [Session] the session whose viewport to broadcast
   # @return [void]
   def broadcast_viewport(session)
     broadcast_system_prompt(session) if session.view_mode == "debug"
 
-    session.viewport_events.each do |event|
-      ActionCable.server.broadcast(stream_name, decorate_event_payload(event, session.view_mode))
+    each_viewport_event(session) do |event, payload|
+      ActionCable.server.broadcast(stream_name, payload)
+    end
+  end
+
+  # Loads the viewport, snapshots it for eviction tracking, and yields
+  # each event with its decorated payload. Snapshot uses snapshot_viewport!
+  # (not recalculate_viewport!) because full viewport refreshes don't need
+  # eviction diffs — clients clear their store before rendering.
+  #
+  # @param session [Session] the session whose viewport to iterate
+  # @yieldparam event [Event] the persisted event record
+  # @yieldparam payload [Hash] decorated payload ready for transmission
+  # @return [void]
+  def each_viewport_event(session)
+    viewport = session.viewport_events
+    session.snapshot_viewport!(viewport.map(&:id))
+
+    viewport.each do |event|
+      yield event, decorate_event_payload(event, session.view_mode)
     end
   end
 
@@ -299,19 +328,38 @@ class SessionChannel < ApplicationCable::Channel
   # @param token [String] validated Anthropic subscription token
   # @return [void]
   def write_anthropic_token(token)
-    creds = Rails.application.credentials
-    existing = begin
-      YAML.safe_load(creds.read) || {}
-    rescue ActiveSupport::EncryptedFile::MissingContentError
-      {}
+    CredentialStore.write("anthropic", "subscription_token" => token)
+  end
+
+  # Serializes a root session with its children for the sessions_list response.
+  # Includes a :children key only when the session has child sessions.
+  #
+  # @param session [Session] root session to serialize
+  # @param counts [Hash<Integer, Integer>] session_id => llm_message count
+  # @return [Hash] with :id, :created_at, :updated_at, :message_count, and optional :children
+  def serialize_session_with_children(session, counts)
+    entry = {
+      id: session.id,
+      name: session.name,
+      created_at: session.created_at.iso8601,
+      updated_at: session.updated_at.iso8601,
+      message_count: counts[session.id] || 0
+    }
+
+    children = session.child_sessions.sort_by(&:created_at)
+    return entry unless children.any?
+
+    entry[:children] = children.map do |child|
+      {
+        id: child.id,
+        name: child.name,
+        processing: child.processing?,
+        message_count: counts[child.id] || 0,
+        created_at: child.created_at.iso8601
+      }
     end
-    existing["anthropic"] ||= {}
-    existing["anthropic"]["subscription_token"] = token
-    creds.write(existing.to_yaml)
-    # Rails memoizes the decrypted config in @config. Without clearing it,
-    # subsequent credential reads return stale data. No public API exists
-    # for cache invalidation as of Rails 8.1.
-    creds.instance_variable_set(:@config, nil)
+
+    entry
   end
 
   def transmit_error(message)

data/app/jobs/agent_request_job.rb

@@ -48,12 +48,20 @@ class AgentRequestJob < ApplicationJob
     # any pending messages after its current loop completes.
     return unless claim_processing(session_id)
 
+    # Run analytical brain BEFORE the main agent on user messages so
+    # activated skills are available for the current response.
+    run_analytical_brain_blocking(session)
+
     agent_loop = AgentLoop.new(session: session)
     loop do
       agent_loop.run
       promoted = session.promote_pending_messages!
       break if promoted == 0
     end
+
+    # Non-blocking analytical brain run after agent completes —
+    # handles post-response updates (renaming, skill changes).
+    session.schedule_analytical_brain!
   ensure
     release_processing(session_id)
     agent_loop&.finalize
@@ -61,6 +69,22 @@ class AgentRequestJob < ApplicationJob
 
   private
 
+  # 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.
   def claim_processing(session_id)

data/app/jobs/analytical_brain_job.rb

@@ -0,0 +1,33 @@
+# 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_event_tokens_job.rb

@@ -18,7 +18,7 @@ class CountEventTokensJob < ApplicationJob
     messages = [{role: event.api_role, content: event.payload["content"].to_s}]
 
     token_count = provider.count_tokens(
-      model: LLM::Client::DEFAULT_MODEL,
+      model: Anima::Settings.model,
       messages: messages
     )
 

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

@@ -9,6 +9,10 @@
 # maintain an ID-indexed store for efficient in-place updates (e.g. when
 # token counts arrive asynchronously from {CountEventTokensJob}).
 #
+# When a new event pushes old events out of the LLM's context window,
+# the broadcast includes `evicted_event_ids` so clients can remove
+# phantom messages that the agent no longer knows about.
+#
 # @example Create broadcast payload
 #   {
 #     "type" => "user_message", "content" => "hello", ...,
@@ -16,6 +20,13 @@
 #     "rendered" => { "basic" => { "role" => "user", "content" => "hello" } }
 #   }
 #
+# @example Broadcast with viewport evictions
+#   {
+#     "type" => "agent_message", "content" => "...", ...,
+#     "id" => 99, "action" => "create",
+#     "evicted_event_ids" => [101, 102, 103]
+#   }
+#
 # @example Update broadcast payload (e.g. token count arrives)
 #   {
 #     "type" => "user_message", "content" => "hello", ...,
@@ -44,13 +55,17 @@ module Event::Broadcasting
   end
 
   # Decorates the event for the session's current view mode and broadcasts
-  # the payload to the session's ActionCable stream.
+  # 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 event
   def broadcast_event(action:)
     return unless session_id
 
-    mode = Session.where(id: session_id).pick(:view_mode) || "basic"
+    session = Session.find_by(id: session_id)
+    return unless session
+
+    mode = session.view_mode
     decorator = EventDecorator.for(self)
     broadcast_payload = payload.merge("id" => id, "action" => action)
 
@@ -58,6 +73,9 @@ module Event::Broadcasting
       broadcast_payload["rendered"] = {mode => decorator.render(mode)}
     end
 
+    evicted_ids = session.recalculate_viewport!
+    broadcast_payload["evicted_event_ids"] = evicted_ids if evicted_ids.any?
+
     ActionCable.server.broadcast("session_#{session_id}", broadcast_payload)
   end
 end

data/app/models/event.rb

@@ -20,7 +20,7 @@ class Event < ApplicationRecord
 
   TYPES = %w[system_message user_message agent_message tool_call tool_response].freeze
   LLM_TYPES = %w[user_message agent_message].freeze
-  CONTEXT_TYPES = %w[user_message agent_message tool_call tool_response].freeze
+  CONTEXT_TYPES = %w[system_message user_message agent_message tool_call tool_response].freeze
   PENDING_STATUS = "pending"
 
   ROLE_MAP = {"user_message" => "user", "agent_message" => "assistant"}.freeze

data/app/models/goal.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+# A persistent objective tracked by the analytical brain during a session.
+# Goals form a two-level hierarchy: root goals represent high-level
+# objectives (semantic episodes), while sub-goals are TODO-style steps
+# rendered as checklist items in the agent's system prompt.
+#
+# The analytical brain creates and completes goals; the main agent sees
+# them in its context window but never manages them directly.
+class Goal < ApplicationRecord
+  STATUSES = %w[active completed].freeze
+
+  belongs_to :session
+  belongs_to :parent_goal, class_name: "Goal", optional: true
+  has_many :sub_goals, -> { order(:created_at) }, class_name: "Goal", foreign_key: :parent_goal_id, dependent: :destroy
+
+  validates :description, presence: true
+  validates :status, inclusion: {in: STATUSES}
+  validate :parent_goal_belongs_to_same_session, if: :parent_goal
+  validate :parent_goal_is_root, if: :parent_goal
+
+  scope :active, -> { where(status: "active") }
+  scope :completed, -> { where(status: "completed") }
+  scope :root, -> { where(parent_goal_id: nil) }
+
+  after_commit :broadcast_goals_update
+
+  # @return [Boolean] true if this goal has been completed
+  def completed? = status == "completed"
+
+  # @return [Boolean] true if this is a root goal (no parent)
+  def root? = !parent_goal_id
+
+  # Cascades completion to all active sub-goals. Called when a root goal
+  # is finished — remaining sub-items are implicitly resolved because
+  # the semantic episode that spawned them has ended.
+  #
+  # Uses +update_all+ to avoid N per-record +after_commit+ broadcasts;
+  # the caller ({AnalyticalBrain::Tools::FinishGoal}) wraps the whole
+  # operation in a transaction so the root goal's single broadcast
+  # includes the cascaded state.
+  #
+  # @return [void]
+  def cascade_completion!
+    now = Time.current
+    sub_goals.active.update_all(status: "completed", completed_at: now, updated_at: now)
+  end
+
+  # Serializes this goal for ActionCable broadcast and TUI display.
+  # Includes nested sub-goals for root goals.
+  #
+  # @return [Hash{String => Object}] with keys "id", "description", "status",
+  #   and "sub_goals" (Array of Hash with "id", "description", "status")
+  def as_summary
+    {
+      "id" => id,
+      "description" => description,
+      "status" => status,
+      "sub_goals" => sub_goals.map { |sub|
+        {"id" => sub.id, "description" => sub.description, "status" => sub.status}
+      }
+    }
+  end
+
+  private
+
+  def parent_goal_belongs_to_same_session
+    return if parent_goal.session_id == session_id
+
+    errors.add(:parent_goal, "must belong to the same session")
+  end
+
+  def parent_goal_is_root
+    return unless parent_goal.parent_goal_id
+
+    errors.add(:parent_goal, "cannot nest deeper than two levels")
+  end
+
+  # Broadcasts goal changes to all clients subscribed to this session.
+  # Mirrors the Session#broadcast_active_skills_update pattern so the
+  # TUI info panel updates reactively.
+  #
+  # @return [void]
+  def broadcast_goals_update
+    ActionCable.server.broadcast("session_#{session_id}", {
+      "action" => "goals_updated",
+      "session_id" => session_id,
+      "goals" => session.goals_summary
+    })
+  end
+end