anima-core 0.1.0 → 0.2.1

data/app/decorators/event_decorator.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+
+# Base decorator for {Event} records, providing multi-resolution rendering
+# for the TUI. Each event type has a dedicated subclass that implements
+# rendering methods for each view mode (basic, verbose, debug).
+#
+# Decorators return structured hashes (not pre-formatted strings) so that
+# the TUI can style and lay out content based on semantic role, without
+# fragile regex parsing. The TUI receives structured data via ActionCable
+# and formats it for display.
+#
+# Subclasses must override {#render_basic}. Verbose and debug modes
+# delegate to basic until subclasses provide their own implementations.
+#
+# @example Decorate an Event AR model
+#   decorator = EventDecorator.for(event)
+#   decorator.render_basic  #=> {role: :user, content: "hello"} or nil
+#
+# @example Render for a specific view mode
+#   decorator = EventDecorator.for(event)
+#   decorator.render("verbose")  #=> {role: :user, content: "hello", timestamp: 1709312325000000000}
+#
+# @example Decorate a raw payload hash (from EventBus)
+#   decorator = EventDecorator.for(type: "user_message", content: "hello")
+#   decorator.render_basic  #=> {role: :user, content: "hello"}
+class EventDecorator < ApplicationDecorator
+  delegate_all
+
+  TOOL_ICON = "\u{1F527}"
+  RETURN_ARROW = "\u21A9"
+  ERROR_ICON = "\u274C"
+
+  DECORATOR_MAP = {
+    "user_message" => "UserMessageDecorator",
+    "agent_message" => "AgentMessageDecorator",
+    "tool_call" => "ToolCallDecorator",
+    "tool_response" => "ToolResponseDecorator",
+    "system_message" => "SystemMessageDecorator"
+  }.freeze
+  private_constant :DECORATOR_MAP
+
+  # Normalizes hash payloads into an Event-like interface so decorators
+  # can use {#payload}, {#event_type}, etc. uniformly on both AR models
+  # and raw EventBus hashes.
+  #
+  # @!attribute event_type [r] the event's type (e.g. "user_message")
+  # @!attribute payload [r] string-keyed hash of event data
+  # @!attribute timestamp [r] nanosecond-precision timestamp
+  # @!attribute token_count [r] cumulative token count
+  EventPayload = Struct.new(:event_type, :payload, :timestamp, :token_count, keyword_init: true) do
+    # Heuristic token estimate matching {Event#estimate_tokens} so decorators
+    # can call it uniformly on both AR models and hash payloads.
+    # @return [Integer] at least 1
+    def estimate_tokens
+      text = if event_type.to_s.in?(%w[tool_call tool_response])
+        payload.to_json
+      else
+        payload&.dig("content").to_s
+      end
+      [(text.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
+    end
+  end
+
+  # Factory returning the appropriate subclass decorator for the given event.
+  # Hashes are normalized via {EventPayload} to provide a uniform interface.
+  #
+  # @param event [Event, Hash] an Event AR model or a raw payload hash
+  # @return [EventDecorator, nil] decorated event, or nil for unknown types
+  def self.for(event)
+    source = wrap_source(event)
+    klass_name = DECORATOR_MAP[source.event_type]
+    return nil unless klass_name
+
+    klass_name.constantize.new(source)
+  end
+
+  RENDER_DISPATCH = {
+    "basic" => :render_basic,
+    "verbose" => :render_verbose,
+    "debug" => :render_debug
+  }.freeze
+  private_constant :RENDER_DISPATCH
+
+  # Dispatches to the render method for the given view mode.
+  #
+  # @param mode [String] one of "basic", "verbose", "debug"
+  # @return [Hash, nil] structured event data, or nil to hide the event
+  # @raise [ArgumentError] if the mode is not a valid view mode
+  def render(mode)
+    method = RENDER_DISPATCH[mode]
+    raise ArgumentError, "Invalid view mode: #{mode.inspect}" unless method
+
+    public_send(method)
+  end
+
+  # @abstract Subclasses must implement to render the event for basic view mode.
+  # @return [Hash, nil] structured event data, or nil to hide the event
+  def render_basic
+    raise NotImplementedError, "#{self.class} must implement #render_basic"
+  end
+
+  # Verbose view mode with timestamps and tool details.
+  # Delegates to {#render_basic} until subclasses provide their own implementations.
+  # @return [Hash, nil] structured event data, or nil to hide the event
+  def render_verbose
+    render_basic
+  end
+
+  # Debug view mode with token counts and system prompts.
+  # Delegates to {#render_basic} until subclasses provide their own implementations.
+  # @return [Hash, nil] structured event data, or nil to hide the event
+  def render_debug
+    render_basic
+  end
+
+  private
+
+  # Token count for display: exact count from {CountEventTokensJob} when
+  # available, heuristic estimate otherwise. Estimated counts are flagged
+  # so the TUI can prefix them with a tilde.
+  #
+  # @return [Hash] `{tokens: Integer, estimated: Boolean}`
+  def token_info
+    count = token_count.to_i
+    if count > 0
+      {tokens: count, estimated: false}
+    else
+      {tokens: estimate_token_count, estimated: true}
+    end
+  end
+
+  # Delegates to the underlying object's heuristic token estimator.
+  # Both {Event} AR models and {EventPayload} structs implement this.
+  #
+  # @return [Integer] at least 1
+  def estimate_token_count
+    object.estimate_tokens
+  end
+
+  # Extracts display content from the event payload.
+  # @return [String, nil]
+  def content
+    payload["content"]
+  end
+
+  # Truncates multi-line text, appending "..." when lines exceed the limit.
+  # @param text [String, nil] text to truncate (nil is coerced to empty string)
+  # @param max_lines [Integer] maximum number of lines to keep
+  # @return [String] truncated text
+  def truncate_lines(text, max_lines:)
+    str = text.to_s
+    lines = str.split("\n")
+    return str unless lines.size > max_lines
+
+    lines.first(max_lines).push("...").join("\n")
+  end
+
+  # Normalizes input to something Draper can wrap.
+  # Event AR models pass through; hashes become EventPayload structs
+  # with string-normalized keys.
+  def self.wrap_source(event)
+    return event unless event.is_a?(Hash)
+
+    normalized = event.transform_keys(&:to_s)
+    EventPayload.new(
+      event_type: normalized["type"].to_s,
+      payload: normalized,
+      timestamp: normalized["timestamp"],
+      token_count: normalized["token_count"]&.to_i || 0
+    )
+  end
+  private_class_method :wrap_source
+end

data/app/decorators/system_message_decorator.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Decorates system_message events for display in the TUI.
+# Hidden in basic mode. Verbose and debug modes return timestamped system info.
+class SystemMessageDecorator < EventDecorator
+  # @return [nil] system messages are hidden in basic mode
+  def render_basic
+    nil
+  end
+
+  # @return [Hash] structured system message data
+  #   `{role: :system, content: String, timestamp: Integer|nil}`
+  def render_verbose
+    {role: :system, content: content, timestamp: timestamp}
+  end
+
+  # @return [Hash] same as verbose — system messages have no additional debug data
+  def render_debug
+    render_verbose
+  end
+end

data/app/decorators/tool_call_decorator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+# Decorates tool_call events for display in the TUI.
+# Hidden in basic mode — tool activity is represented by the
+# aggregated tool counter instead. Verbose mode returns tool name
+# and a formatted preview of the input arguments. Debug mode shows
+# full untruncated input as pretty-printed JSON with tool_use_id.
+class ToolCallDecorator < EventDecorator
+  # @return [nil] tool calls are hidden in basic mode
+  def render_basic
+    nil
+  end
+
+  # @return [Hash] structured tool call data
+  #   `{role: :tool_call, tool: String, input: String, timestamp: Integer|nil}`
+  def render_verbose
+    {role: :tool_call, tool: payload["tool_name"], input: format_input, timestamp: timestamp}
+  end
+
+  # @return [Hash] full tool call data with untruncated input and tool_use_id
+  #   `{role: :tool_call, tool: String, input: String, tool_use_id: String|nil, timestamp: Integer|nil}`
+  def render_debug
+    {
+      role: :tool_call,
+      tool: payload["tool_name"],
+      input: JSON.pretty_generate(payload["tool_input"] || {}),
+      tool_use_id: payload["tool_use_id"],
+      timestamp: timestamp
+    }
+  end
+
+  private
+
+  # Formats tool input for display, with tool-specific formatting for
+  # known tools and generic JSON fallback for others.
+  # @return [String] formatted input preview
+  def format_input
+    input = payload["tool_input"]
+    case payload["tool_name"]
+    when "bash"
+      "$ #{input&.dig("command")}"
+    when "web_get"
+      "GET #{input&.dig("url")}"
+    else
+      truncate_lines(input.to_json, max_lines: 2)
+    end
+  end
+end

data/app/decorators/tool_response_decorator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# Decorates tool_response events for display in the TUI.
+# Hidden in basic mode — tool activity is represented by the
+# aggregated tool counter instead. Verbose mode returns truncated
+# output with a success/failure indicator. Debug mode shows full
+# untruncated output with tool_use_id and estimated token count.
+class ToolResponseDecorator < EventDecorator
+  # @return [nil] tool responses are hidden in basic mode
+  def render_basic
+    nil
+  end
+
+  # @return [Hash] structured tool response data
+  #   `{role: :tool_response, content: String, success: Boolean, timestamp: Integer|nil}`
+  def render_verbose
+    {
+      role: :tool_response,
+      content: truncate_lines(content, max_lines: 3),
+      success: payload["success"] != false,
+      timestamp: timestamp
+    }
+  end
+
+  # @return [Hash] full tool response data with untruncated content, tool_use_id, and token estimate
+  #   `{role: :tool_response, content: String, success: Boolean, tool_use_id: String|nil,
+  #     timestamp: Integer|nil, tokens: Integer, estimated: Boolean}`
+  def render_debug
+    {
+      role: :tool_response,
+      content: content,
+      success: payload["success"] != false,
+      tool_use_id: payload["tool_use_id"],
+      timestamp: timestamp
+    }.merge(token_info)
+  end
+end

data/app/decorators/user_message_decorator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Decorates user_message events for display in the TUI.
+# Basic mode returns role and content. Verbose mode adds a timestamp.
+# Debug mode adds token count (exact when counted, estimated when not).
+class UserMessageDecorator < EventDecorator
+  # @return [Hash] structured user message data
+  #   `{role: :user, content: String}`
+  def render_basic
+    {role: :user, content: content}
+  end
+
+  # @return [Hash] structured user message with nanosecond timestamp
+  #   `{role: :user, content: String, timestamp: Integer|nil}`
+  def render_verbose
+    {role: :user, content: content, timestamp: timestamp}
+  end
+
+  # @return [Hash] verbose output plus token count for debugging
+  #   `{role: :user, content: String, timestamp: Integer|nil, tokens: Integer, estimated: Boolean}`
+  def render_debug
+    render_verbose.merge(token_info)
+  end
+end

data/app/jobs/agent_request_job.rb

@@ -0,0 +1,59 @@
+# 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).
+#
+# Emits events via {Events::Bus} as it progresses, making results visible
+# to any subscriber (TUI, WebSocket clients). All retry and failure
+# notifications are emitted as {Events::SystemMessage} to avoid polluting
+# the LLM context window.
+#
+# @example Inline execution (TUI)
+#   AgentRequestJob.perform_now(session.id)
+#
+# @example Background execution (future Brain/TUI separation)
+#   AgentRequestJob.perform_later(session.id)
+class AgentRequestJob < ApplicationJob
+  queue_as :default
+
+  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|
+    Events::Bus.emit(Events::SystemMessage.new(
+      content: "Authentication failed: #{error.message}",
+      session_id: job.arguments.first
+    ))
+  end
+
+  # @param session_id [Integer] ID of the session to process
+  def perform(session_id)
+    session = Session.find(session_id)
+    agent_loop = AgentLoop.new(session: session)
+    agent_loop.run
+  ensure
+    agent_loop&.finalize
+  end
+
+  private
+
+  # 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/count_event_tokens_job.rb

@@ -6,7 +6,7 @@
 class CountEventTokensJob < ApplicationJob
   queue_as :default
 
-  retry_on Providers::Anthropic::Error, wait: :exponentially_longer, attempts: 3
+  retry_on Providers::Anthropic::Error, wait: :polynomially_longer, attempts: 3
   discard_on ActiveRecord::RecordNotFound
 
   # @param event_id [Integer] the Event record to count tokens for

data/app/models/event.rb

@@ -22,6 +22,9 @@ class Event < ApplicationRecord
 
   ROLE_MAP = {"user_message" => "user", "agent_message" => "assistant"}.freeze
 
+  # Heuristic: average bytes per token for English prose.
+  BYTES_PER_TOKEN = 4
+
   belongs_to :session
 
   validates :event_type, presence: true, inclusion: {in: TYPES}
@@ -56,6 +59,20 @@ class Event < ApplicationRecord
     event_type.in?(CONTEXT_TYPES)
   end
 
+  # Heuristic token estimate: ~4 bytes per token for English prose.
+  # Tool events are estimated from the full payload JSON since tool_input
+  # and tool metadata contribute to token count. Messages use content only.
+  #
+  # @return [Integer] estimated token count (at least 1)
+  def estimate_tokens
+    text = if event_type.in?(%w[tool_call tool_response])
+      payload.to_json
+    else
+      payload["content"].to_s
+    end
+    [(text.bytesize / BYTES_PER_TOKEN.to_f).ceil, 1].max
+  end
+
   private
 
   def schedule_token_count

data/app/models/session.rb

@@ -7,23 +7,29 @@ class Session < ApplicationRecord
   # Claude Sonnet 4 context window minus system prompt reserve.
   DEFAULT_TOKEN_BUDGET = 190_000
 
-  # Heuristic: average bytes per token for English prose.
-  BYTES_PER_TOKEN = 4
+  VIEW_MODES = %w[basic verbose debug].freeze
 
   has_many :events, -> { order(:id) }, dependent: :destroy
 
-  # Builds the message array expected by the Anthropic Messages API.
-  # Includes user/agent messages and tool call/response events in
-  # Anthropic's wire format. Consecutive tool_call events are grouped
-  # into a single assistant message; consecutive tool_response events
-  # are grouped into a single user message with tool_result blocks.
+  validates :view_mode, inclusion: {in: VIEW_MODES}
+
+  scope :recent, ->(limit = 10) { order(updated_at: :desc).limit(limit) }
+
+  # Cycles to the next view mode: basic → verbose → debug → basic.
   #
+  # @return [String] the next view mode in the cycle
+  def next_view_mode
+    current_index = VIEW_MODES.index(view_mode) || 0
+    VIEW_MODES[(current_index + 1) % VIEW_MODES.size]
+  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.
   #
   # @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)
+  # @return [Array<Event>] chronologically ordered
+  def viewport_events(token_budget: DEFAULT_TOKEN_BUDGET)
     selected = []
     remaining = token_budget
 
@@ -35,7 +41,28 @@ class Session < ApplicationRecord
       remaining -= cost
     end
 
-    assemble_messages(selected.reverse)
+    selected.reverse
+  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.
+  #
+  # @return [String, nil] the system prompt text, or nil if not configured
+  def system_prompt
+    nil
+  end
+
+  # Builds the message array expected by the Anthropic Messages API.
+  # Includes user/agent messages and tool call/response events in
+  # Anthropic's wire format. Consecutive tool_call events are grouped
+  # into a single assistant message; consecutive tool_response events
+  # are grouped into a single user message with tool_result blocks.
+  #
+  # @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)
+    assemble_messages(viewport_events(token_budget: token_budget))
   end
 
   private
@@ -88,18 +115,12 @@ class Session < ApplicationRecord
     }
   end
 
-  # Rough estimate for events not yet counted by the background job.
-  # For tool events, estimates from the full payload since tool_input
-  # and tool metadata contribute to token count.
+  # Delegates to {Event#estimate_tokens} for events not yet counted
+  # by the background job.
   #
   # @param event [Event]
   # @return [Integer] at least 1
   def estimate_tokens(event)
-    text = if event.event_type.in?(%w[tool_call tool_response])
-      event.payload.to_json
-    else
-      event.payload["content"].to_s
-    end
-    [(text.bytesize / BYTES_PER_TOKEN.to_f).ceil, 1].max
+    event.estimate_tokens
   end
 end

data/bin/jobs

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+
+require_relative "../config/environment"
+require "solid_queue/cli"
+
+SolidQueue::Cli.start(ARGV)

data/bin/rails

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+APP_PATH = File.expand_path("../config/application", __dir__)
+require_relative "../config/boot"
+require "rails/commands"

data/bin/rake

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../config/boot"
+require "rake"
+Rake.application.run

data/config/application.rb

@@ -6,7 +6,10 @@ require "rails"
 require "active_model/railtie"
 require "active_record/railtie"
 require "active_job/railtie"
+require "action_cable/engine"
 require "rails/test_unit/railtie"
+require "draper"
+require "solid_cable"
 require "solid_queue"
 
 Bundler.require(*Rails.groups) if ENV.key?("BUNDLE_GEMFILE")
@@ -20,6 +23,8 @@ module Anima
     config.active_job.queue_adapter = :solid_queue
     config.solid_queue.connects_to = {database: {writing: :queue}}
 
+    config.action_cable.disable_request_forgery_protection = true
+
     anima_home = Pathname.new(File.expand_path("~/.anima"))
 
     config.paths["log"] = [anima_home.join("log", "#{Rails.env}.log").to_s]

data/config/cable.yml

@@ -0,0 +1,14 @@
+development:
+  adapter: solid_cable
+  connects_to:
+    database:
+      writing: cable
+
+test:
+  adapter: test
+
+production:
+  adapter: solid_cable
+  connects_to:
+    database:
+      writing: cable

data/config/database.yml

@@ -13,6 +13,10 @@ development:
     <<: *default
     database: <%= File.join(anima_home, "db", "development_queue.sqlite3") %>
     migrations_paths: db/queue_migrate
+  cable:
+    <<: *default
+    database: <%= File.join(anima_home, "db", "development_cable.sqlite3") %>
+    migrations_paths: db/cable_migrate
 
 test:
   primary:
@@ -22,6 +26,10 @@ test:
     <<: *default
     database: <%= File.join(anima_home, "db", "test_queue.sqlite3") %>
     migrations_paths: db/queue_migrate
+  cable:
+    <<: *default
+    database: <%= File.join(anima_home, "db", "test_cable.sqlite3") %>
+    migrations_paths: db/cable_migrate
 
 production:
   primary:
@@ -31,3 +39,7 @@ production:
     <<: *default
     database: <%= File.join(anima_home, "db", "production_queue.sqlite3") %>
     migrations_paths: db/queue_migrate
+  cable:
+    <<: *default
+    database: <%= File.join(anima_home, "db", "production_cable.sqlite3") %>
+    migrations_paths: db/cable_migrate

data/config/initializers/event_subscribers.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Registers global EventBus subscribers at boot time.
+# Subscribers registered here receive all events regardless of which
+# process emitted them (brain server, background job, etc.).
+Rails.application.config.after_initialize do
+  # Global persister handles events from all sessions (brain server, background jobs).
+  # Skipped in test — specs manage their own persisters for isolation.
+  Events::Bus.subscribe(Events::Subscribers::Persister.new) unless Rails.env.test?
+  Events::Bus.subscribe(Events::Subscribers::ActionCableBridge.instance)
+end

data/config/puma.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Anima brain server — serves Action Cable WebSocket connections
+# and health check endpoint. Port 42134 by default.
+
+threads_count = ENV.fetch("RAILS_MAX_THREADS", 3)
+threads threads_count, threads_count
+
+port ENV.fetch("PORT", 42134)
+
+pidfile ENV.fetch("PIDFILE", File.expand_path("~/.anima/tmp/pids/puma.pid"))
+
+plugin :tmp_restart

data/config/routes.rb

@@ -1,4 +1,12 @@
 # frozen_string_literal: true
 
 Rails.application.routes.draw do
+  mount ActionCable.server => "/cable"
+  get "up", to: "rails/health#show", as: :rails_health_check
+
+  namespace :api do
+    resources :sessions, only: [:create] do
+      get :current, on: :collection
+    end
+  end
 end

data/config.ru

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+require_relative "config/environment"
+
+run Rails.application

data/db/cable_schema.rb

@@ -0,0 +1,23 @@
+# This file is auto-generated from the current state of the database. Instead
+# of editing this file, please use the migrations feature of Active Record to
+# incrementally modify your database, and then regenerate this schema definition.
+#
+# This file is the source Rails uses to define your schema when running `bin/rails
+# db:schema:load`. When creating a new database, `bin/rails db:schema:load` tends to
+# be faster and is potentially less error prone than running all of your
+# migrations from scratch. Old migrations may fail to apply correctly if those
+# migrations use external dependencies or application code.
+#
+# It's strongly recommended that you check this file into your version control system.
+
+ActiveRecord::Schema[8.1].define(version: 1) do
+  create_table "solid_cable_messages", force: :cascade do |t|
+    t.binary "channel", limit: 1024, null: false
+    t.integer "channel_hash", limit: 8, null: false
+    t.datetime "created_at", null: false
+    t.binary "payload", limit: 536870912, null: false
+    t.index ["channel"], name: "index_solid_cable_messages_on_channel"
+    t.index ["channel_hash"], name: "index_solid_cable_messages_on_channel_hash"
+    t.index ["created_at"], name: "index_solid_cable_messages_on_created_at"
+  end
+end

data/db/migrate/20260312170000_add_view_mode_to_sessions.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class AddViewModeToSessions < ActiveRecord::Migration[8.1]
+  def change
+    add_column :sessions, :view_mode, :string, default: "basic", null: false
+  end
+end