anima-core 0.3.0 → 1.0.1

data/app/models/session.rb

@@ -3,17 +3,31 @@
 # A conversation session — the fundamental unit of agent interaction.
 # Owns an ordered stream of {Event} records representing everything
 # that happened: user messages, agent responses, tool calls, etc.
+#
+# Sessions form a hierarchy: a main session can spawn child sessions
+# (sub-agents) that inherit the parent's viewport context at fork time.
 class Session < ApplicationRecord
-  # Claude Sonnet 4 context window minus system prompt reserve.
-  DEFAULT_TOKEN_BUDGET = 190_000
+  class MissingSoulError < StandardError; end
 
   VIEW_MODES = %w[basic verbose debug].freeze
 
+  serialize :granted_tools, coder: JSON
+
   has_many :events, -> { order(:id) }, dependent: :destroy
+  has_many :goals, dependent: :destroy
+
+  belongs_to :parent_session, class_name: "Session", optional: true
+  has_many :child_sessions, class_name: "Session", foreign_key: :parent_session_id, dependent: :destroy
 
   validates :view_mode, inclusion: {in: VIEW_MODES}
+  validates :name, length: {maximum: 255}, allow_nil: true
+
+  after_update_commit :broadcast_name_update, if: :saved_change_to_name?
+  after_update_commit :broadcast_active_skills_update, if: :saved_change_to_active_skills?
+  after_update_commit :broadcast_active_workflow_update, if: :saved_change_to_active_workflow?
 
   scope :recent, ->(limit = 10) { order(updated_at: :desc).limit(limit) }
+  scope :root_sessions, -> { where(parent_session_id: nil) }
 
   # Cycles to the next view mode: basic → verbose → debug → basic.
   #
@@ -23,39 +37,167 @@ class Session < ApplicationRecord
     VIEW_MODES[(current_index + 1) % VIEW_MODES.size]
   end
 
+  # @return [Boolean] true if this session is a sub-agent (has a parent)
+  def sub_agent?
+    parent_session_id.present?
+  end
+
+  # Enqueues the analytical brain to perform background maintenance on
+  # this session. Currently handles session naming; future phases add
+  # skill activation, goal tracking, and memory.
+  #
+  # Runs after the first exchange and periodically as the conversation
+  # evolves, so the name stays relevant to the current topic.
+  #
+  # @return [void]
+  def schedule_analytical_brain!
+    return if sub_agent?
+
+    count = events.llm_messages.count
+    return if count < 2
+    # Already named — only regenerate at interval boundaries (30, 60, 90, …)
+    return if name.present? && (count % Anima::Settings.name_generation_interval != 0)
+
+    AnalyticalBrainJob.perform_later(id)
+  end
+
   # Returns the events currently visible in the LLM context window.
   # Walks events newest-first and includes them until the token budget
   # is exhausted. Events are full-size or excluded entirely.
   #
+  # Sub-agent sessions inherit parent context via virtual viewport:
+  # child events are prioritized and fill the budget first (newest-first),
+  # then parent events from before the fork point fill the remaining budget.
+  # The final array is chronological: parent events first, then child events.
+  #
   # @param token_budget [Integer] maximum tokens to include (positive)
   # @param include_pending [Boolean] whether to include pending messages (true for
   #   display, false for LLM context assembly)
   # @return [Array<Event>] chronologically ordered
-  def viewport_events(token_budget: DEFAULT_TOKEN_BUDGET, include_pending: true)
-    scope = events.context_events
-    scope = scope.deliverable unless include_pending
+  def viewport_events(token_budget: Anima::Settings.token_budget, include_pending: true)
+    own_events = select_events(own_event_scope(include_pending), budget: token_budget)
+    remaining = token_budget - own_events.sum { |e| event_token_cost(e) }
 
-    selected = []
-    remaining = token_budget
+    if sub_agent? && remaining > 0
+      parent_events = select_events(parent_event_scope(include_pending), budget: remaining)
+      trim_trailing_tool_calls(parent_events) + own_events
+    else
+      own_events
+    end
+  end
 
-    scope.reorder(id: :desc).each do |event|
-      cost = (event.token_count > 0) ? event.token_count : estimate_tokens(event)
-      break if cost > remaining && selected.any?
+  # Recalculates the viewport and returns IDs of events evicted since the
+  # last snapshot. Updates the stored viewport_event_ids atomically.
+  # Piggybacks on event broadcasts to notify clients which messages left
+  # the LLM's context window.
+  #
+  # @return [Array<Integer>] IDs of events no longer in the viewport
+  def recalculate_viewport!
+    new_ids = viewport_events.map(&:id)
+    old_ids = viewport_event_ids
 
-      selected << event
-      remaining -= cost
-    end
+    evicted = old_ids - new_ids
+    update_column(:viewport_event_ids, new_ids) if old_ids != new_ids
+    evicted
+  end
 
-    selected.reverse
+  # Overwrites the viewport snapshot without computing evictions.
+  # Used when transmitting or broadcasting a full viewport refresh,
+  # where eviction notifications are unnecessary (clients clear their
+  # store first).
+  #
+  # @param ids [Array<Integer>] event IDs now in the viewport
+  # @return [void]
+  def snapshot_viewport!(ids)
+    update_column(:viewport_event_ids, ids)
+  end
+
+  # Returns the system prompt for this session.
+  # Sub-agent sessions use their stored prompt. Main sessions assemble
+  # a system prompt from active skills and current goals.
+  #
+  # @param environment_context [String, nil] pre-assembled environment block
+  #   from {EnvironmentProbe}; injected between soul and expertise sections
+  # @return [String, nil] the system prompt text, or nil when nothing to inject
+  def system_prompt(environment_context: nil)
+    sub_agent? ? prompt : assemble_system_prompt(environment_context: environment_context)
+  end
+
+  # Activates a skill on this session. Validates the skill exists in the
+  # registry, adds it to active_skills, and persists.
+  #
+  # @param skill_name [String] name of the skill to activate
+  # @return [Skills::Definition] the activated skill
+  # @raise [Skills::InvalidDefinitionError] if skill not found in registry
+  # @raise [ActiveRecord::RecordInvalid] if save fails
+  def activate_skill(skill_name)
+    definition = Skills::Registry.instance.find(skill_name)
+    raise Skills::InvalidDefinitionError, "Unknown skill: #{skill_name}" unless definition
+
+    return definition if active_skills.include?(skill_name)
+
+    self.active_skills = active_skills + [skill_name]
+    save!
+    definition
+  end
+
+  # Deactivates a skill on this session. Removes it from active_skills and persists.
+  #
+  # @param skill_name [String] name of the skill to deactivate
+  # @return [void]
+  def deactivate_skill(skill_name)
+    return unless active_skills.include?(skill_name)
+
+    self.active_skills = active_skills - [skill_name]
+    save!
+  end
+
+  # Activates a workflow on this session. Validates the workflow exists in the
+  # registry, sets it as the active workflow, and persists. Only one workflow
+  # can be active at a time — activating a new one replaces the previous.
+  #
+  # @param workflow_name [String] name of the workflow to activate
+  # @return [Workflows::Definition] the activated workflow
+  # @raise [Workflows::InvalidDefinitionError] if workflow not found in registry
+  # @raise [ActiveRecord::RecordInvalid] if save fails
+  def activate_workflow(workflow_name)
+    definition = Workflows::Registry.instance.find(workflow_name)
+    raise Workflows::InvalidDefinitionError, "Unknown workflow: #{workflow_name}" unless definition
+
+    return definition if active_workflow == workflow_name
+
+    self.active_workflow = workflow_name
+    save!
+    definition
+  end
+
+  # Deactivates the current workflow on this session.
+  #
+  # @return [void]
+  def deactivate_workflow
+    return unless active_workflow.present?
+
+    self.active_workflow = nil
+    save!
+  end
+
+  # Assembles the system prompt: soul first, then environment context,
+  # then skills/workflow, then goals.
+  # The soul is always present — "who am I" before "what can I do."
+  #
+  # @param environment_context [String, nil] pre-assembled environment block
+  # @return [String] composed system prompt
+  def assemble_system_prompt(environment_context: nil)
+    [assemble_soul_section, environment_context, assemble_expertise_section, assemble_goals_section].compact.join("\n\n")
   end
 
-  # Returns the assembled system prompt for this session.
-  # The system prompt includes system instructions, goals, and memories.
-  # Currently a placeholder — these subsystems are not yet implemented.
+  # Serializes active goals as a lightweight summary for ActionCable
+  # broadcasts and TUI display. Returns a nested structure: root goals
+  # with their sub-goals inlined.
   #
-  # @return [String, nil] the system prompt text, or nil if not configured
-  def system_prompt
-    nil
+  # @return [Array<Hash>] each with :id, :description, :status, and :sub_goals
+  def goals_summary
+    goals.root.includes(:sub_goals).order(:created_at).map(&:as_summary)
   end
 
   # Builds the message array expected by the Anthropic Messages API.
@@ -67,7 +209,7 @@ class Session < ApplicationRecord
   #
   # @param token_budget [Integer] maximum tokens to include (positive)
   # @return [Array<Hash>] Anthropic Messages API format
-  def messages_for_llm(token_budget: DEFAULT_TOKEN_BUDGET)
+  def messages_for_llm(token_budget: Anima::Settings.token_budget)
     assemble_messages(viewport_events(token_budget: token_budget, include_pending: false))
   end
 
@@ -87,7 +229,175 @@ class Session < ApplicationRecord
 
   private
 
+  # Reads the soul file — the agent's self-authored identity.
+  # Loaded as the first section of every system prompt, before skills,
+  # workflows, and goals.
+  #
+  # @return [String] soul content
+  # @raise [MissingSoulError] when the soul file does not exist
+  def assemble_soul_section
+    path = Anima::Settings.soul_path
+    unless File.exist?(path)
+      raise MissingSoulError, "Soul file not found: #{path}. Run `anima install` to create it."
+    end
+
+    File.read(path).strip
+  end
+
+  # Assembles the expertise section of the system prompt from active skills
+  # and the active workflow. Both are injected into the same "Your Expertise"
+  # section — the main agent treats them identically as domain knowledge.
+  #
+  # @return [String, nil] expertise section, or nil when nothing is active
+  def assemble_expertise_section
+    sections = active_skills.filter_map do |skill_name|
+      definition = Skills::Registry.instance.find(skill_name)
+      format_expertise_section(definition, skill_name)
+    end
+
+    if active_workflow.present?
+      definition = Workflows::Registry.instance.find(active_workflow)
+      sections << format_expertise_section(definition, active_workflow) if definition
+    end
+
+    return if sections.empty?
+
+    "## Your Expertise\n\nYou know this deeply. Now's your chance to put it to work.\n\n#{sections.join("\n\n")}"
+  end
+
+  # Assembles the goals section of the system prompt.
+  # Active root goals render as `###` headings with sub-goal checkboxes.
+  # Completed root goals collapse to a single strikethrough line.
+  #
+  # @return [String, nil] goals section, or nil when no goals exist
+  def assemble_goals_section
+    root_goals = goals.root.includes(:sub_goals).order(:created_at)
+    return if root_goals.empty?
+
+    entries = root_goals.map { |goal| render_goal_markdown(goal) }
+    "## Current Goals\n\n#{entries.join("\n\n")}"
+  end
+
+  # Renders a single root goal with its sub-goals as Markdown.
+  # Active goals show full hierarchy; completed goals collapse to one line.
+  #
+  # @param goal [Goal] a root goal
+  # @return [String] Markdown fragment
+  def render_goal_markdown(goal)
+    description = goal.description
+    return "### ~~#{description}~~ ✓" if goal.completed?
+
+    lines = ["### #{description}"]
+    goal.sub_goals.each do |sub|
+      checkbox = sub.completed? ? "[x]" : "[ ]"
+      lines << "- #{checkbox} #{sub.description}"
+    end
+    lines.join("\n")
+  end
+
+  # Formats a definition (skill or workflow) as a Markdown section for the
+  # expertise prompt. Extracts the first Markdown heading from content for
+  # the section title; falls back to the definition name when content has
+  # no heading.
+  #
+  # @param definition [Skills::Definition, Workflows::Definition, nil] the definition to format
+  # @param fallback_name [String] name to use if content has no heading
+  # @return [String, nil] formatted section, or nil if definition is nil
+  def format_expertise_section(definition, fallback_name)
+    return unless definition
+
+    content = definition.content
+    heading = content.lines.first&.sub(/^#+ /, "")&.strip || fallback_name
+    "### #{heading}\n\n#{content}"
+  end
+
+  # Broadcasts a name change to all clients subscribed to this session.
+  # Triggered by after_update_commit so clients see name updates in real time.
+  #
+  # @return [void]
+  def broadcast_name_update
+    ActionCable.server.broadcast("session_#{id}", {
+      "action" => "session_name_updated",
+      "session_id" => id,
+      "name" => name
+    })
+  end
+
+  # Broadcasts active skill changes to all clients subscribed to this session.
+  # Triggered by after_update_commit so the TUI info panel updates reactively.
+  #
+  # @return [void]
+  def broadcast_active_skills_update
+    ActionCable.server.broadcast("session_#{id}", {
+      "action" => "active_skills_updated",
+      "session_id" => id,
+      "active_skills" => active_skills
+    })
+  end
+
+  # Broadcasts active workflow change to all clients subscribed to this session.
+  # Triggered by after_update_commit so the TUI info panel updates reactively.
+  #
+  # @return [void]
+  def broadcast_active_workflow_update
+    ActionCable.server.broadcast("session_#{id}", {
+      "action" => "active_workflow_updated",
+      "session_id" => id,
+      "active_workflow" => active_workflow
+    })
+  end
+
+  # Scopes own events for viewport assembly.
+  # @return [ActiveRecord::Relation]
+  def own_event_scope(include_pending)
+    scope = events.context_events
+    include_pending ? scope : scope.deliverable
+  end
+
+  # Scopes parent events created before this session's fork point.
+  # @return [ActiveRecord::Relation]
+  def parent_event_scope(include_pending)
+    scope = parent_session.events.context_events.where(created_at: ...created_at)
+    include_pending ? scope : scope.deliverable
+  end
+
+  # Walks events newest-first, selecting until the token budget is exhausted.
+  # Always includes at least the newest event even if it exceeds budget.
+  #
+  # @param scope [ActiveRecord::Relation] event scope to select from
+  # @param budget [Integer] maximum tokens to include
+  # @return [Array<Event>] chronologically ordered
+  def select_events(scope, budget:)
+    selected = []
+    remaining = budget
+
+    scope.reorder(id: :desc).each do |event|
+      cost = event_token_cost(event)
+      break if cost > remaining && selected.any?
+
+      selected << event
+      remaining -= cost
+    end
+
+    selected.reverse
+  end
+
+  # @return [Integer] token cost, using cached count or heuristic estimate
+  def event_token_cost(event)
+    (event.token_count > 0) ? event.token_count : estimate_tokens(event)
+  end
+
+  # Removes trailing tool_call events that lack matching tool_response.
+  # Prevents orphaned tool_use blocks at the parent/child viewport boundary
+  # (the spawn_subagent/spawn_specialist tool_call is emitted before the child exists,
+  # but its tool_response comes after — so the cutoff can split them).
+  def trim_trailing_tool_calls(event_list)
+    event_list.pop while event_list.last&.event_type == "tool_call"
+    event_list
+  end
+
   # Converts a chronological list of events into Anthropic wire-format messages.
+  # Prepends a compact timestamp to each user message for LLM time awareness.
   # Groups consecutive tool_call events into one assistant message and
   # consecutive tool_response events into one user message.
   #
@@ -97,13 +407,17 @@ class Session < ApplicationRecord
     events.each_with_object([]) do |event, messages|
       case event.event_type
       when "user_message"
-        messages << {role: "user", content: event.payload["content"].to_s}
+        content = "#{format_event_time(event.timestamp)}\n#{event.payload["content"]}"
+        messages << {role: "user", content: content}
       when "agent_message"
         messages << {role: "assistant", content: event.payload["content"].to_s}
       when "tool_call"
         append_grouped_block(messages, "assistant", tool_use_block(event.payload))
       when "tool_response"
         append_grouped_block(messages, "user", tool_result_block(event.payload))
+      when "system_message"
+        # Wrapped as user role with prefix — Claude API has no system role in conversation history
+        messages << {role: "user", content: "[system] #{event.payload["content"]}"}
       end
     end
   end
@@ -135,6 +449,17 @@ class Session < ApplicationRecord
     }
   end
 
+  # Formats an event's nanosecond timestamp as a compact time prefix for LLM context.
+  # Gives the agent awareness of time of day, day of week, and pauses between messages.
+  #
+  # @param timestamp_ns [Integer] nanoseconds since epoch
+  # @return [String] e.g. "Sat Mar 14 09:51"
+  # @example
+  #   format_event_time(1_710_406_260_000_000_000) #=> "Thu Mar 14 09:51"
+  def format_event_time(timestamp_ns)
+    Time.at(timestamp_ns / 1_000_000_000.0).strftime("%a %b %-d %H:%M")
+  end
+
   # Delegates to {Event#estimate_tokens} for events not yet counted
   # by the background job.
   #

data/config/application.rb

@@ -14,6 +14,8 @@ require "solid_queue"
 
 Bundler.require(*Rails.groups) if ENV.key?("BUNDLE_GEMFILE")
 
+require_relative "../lib/anima"
+
 module Anima
   class Application < Rails::Application
     config.load_defaults 8.1

data/db/migrate/20260314075248_add_subagent_support_to_sessions.rb

@@ -0,0 +1,6 @@
+class AddSubagentSupportToSessions < ActiveRecord::Migration[8.1]
+  def change
+    add_reference :sessions, :parent_session, foreign_key: {to_table: :sessions}, null: true
+    add_column :sessions, :prompt, :text
+  end
+end

data/db/migrate/20260314112417_add_granted_tools_to_sessions.rb

@@ -0,0 +1,5 @@
+class AddGrantedToolsToSessions < ActiveRecord::Migration[8.1]
+  def change
+    add_column :sessions, :granted_tools, :text
+  end
+end

data/db/migrate/20260314140000_add_name_to_sessions.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddNameToSessions < ActiveRecord::Migration[8.1]
+  def change
+    add_column :sessions, :name, :string
+  end
+end

data/db/migrate/20260314150000_add_viewport_event_ids_to_sessions.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddViewportEventIdsToSessions < ActiveRecord::Migration[8.1]
+  def change
+    add_column :sessions, :viewport_event_ids, :json, default: [], null: false
+  end
+end

data/db/migrate/20260315100000_add_active_skills_to_sessions.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddActiveSkillsToSessions < ActiveRecord::Migration[8.1]
+  def change
+    add_column :sessions, :active_skills, :json, default: [], null: false
+  end
+end

data/db/migrate/20260315140843_create_goals.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+class CreateGoals < ActiveRecord::Migration[8.1]
+  def change
+    create_table :goals do |t|
+      t.references :session, null: false, foreign_key: true
+      t.references :parent_goal, foreign_key: {to_table: :goals}, null: true
+      t.text :description, null: false
+      t.string :status, default: "active", null: false
+
+      t.timestamps
+    end
+
+    add_index :goals, [:session_id, :status]
+  end
+end

data/db/migrate/20260315144837_add_completed_at_to_goals.rb

@@ -0,0 +1,5 @@
+class AddCompletedAtToGoals < ActiveRecord::Migration[8.1]
+  def change
+    add_column :goals, :completed_at, :datetime
+  end
+end

data/db/migrate/20260315191105_add_active_workflow_to_sessions.rb

@@ -0,0 +1,5 @@
+class AddActiveWorkflowToSessions < ActiveRecord::Migration[8.1]
+  def change
+    add_column :sessions, :active_workflow, :string
+  end
+end

data/lib/agent_loop.rb

@@ -73,7 +73,15 @@ class AgentLoop
     @registry ||= build_tool_registry
 
     messages = @session.messages_for_llm
-    response = @client.chat_with_tools(messages, registry: @registry, session_id: @session.id)
+    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
+
+    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
@@ -84,17 +92,65 @@ class AgentLoop
     @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].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
 
-  # Builds the default tool registry with all available tools.
-  # @return [Tools::Registry] registry with all available tools
+  # 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).
+  # 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
-    registry = Tools::Registry.new(context: {shell_session: @shell_session})
-    registry.register(Tools::Bash)
-    registry.register(Tools::Read)
-    registry.register(Tools::Write)
-    registry.register(Tools::Edit)
-    registry.register(Tools::WebGet)
+    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::ReturnResult)
+    else
+      registry.register(Tools::SpawnSubagent)
+      registry.register(Tools::SpawnSpecialist)
+      registry.register(Tools::RequestFeature)
+    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.
+  #
+  # @return [Array<Class<Tools::Base>>] tool classes to register
+  def granted_standard_tools
+    return STANDARD_TOOLS unless @session.granted_tools
+
+    @session.granted_tools.filter_map { |name| STANDARD_TOOLS_BY_NAME[name] }
+  end
 end