anima-core 0.2.0 → 0.3.0

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,35 @@
+# 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).
+# Pending messages include `status: "pending"` so the TUI renders them
+# with a visual indicator (dimmed, clock icon).
+class UserMessageDecorator < EventDecorator
+  # @return [Hash] structured user message data
+  #   `{role: :user, content: String}` or with `status: "pending"` when queued
+  def render_basic
+    base = {role: :user, content: content}
+    base[:status] = "pending" if pending?
+    base
+  end
+
+  # @return [Hash] structured user message with nanosecond timestamp
+  def render_verbose
+    base = {role: :user, content: content, timestamp: timestamp}
+    base[:status] = "pending" if pending?
+    base
+  end
+
+  # @return [Hash] verbose output plus token count for debugging
+  def render_debug
+    render_verbose.merge(token_info)
+  end
+
+  private
+
+  # @return [Boolean] true when this message is queued but not yet sent to LLM
+  def pending?
+    payload["status"] == Event::PENDING_STATUS
+  end
+end

data/app/jobs/agent_request_job.rb

@@ -26,23 +26,52 @@ class AgentRequestJob < ApplicationJob
 
   discard_on ActiveRecord::RecordNotFound
   discard_on Providers::Anthropic::AuthenticationError do |job, error|
+    session_id = job.arguments.first
+    # Persistent system message for the event log
     Events::Bus.emit(Events::SystemMessage.new(
       content: "Authentication failed: #{error.message}",
-      session_id: job.arguments.first
+      session_id: session_id
     ))
+    # Transient signal to trigger TUI token setup popup (not persisted)
+    ActionCable.server.broadcast(
+      "session_#{session_id}",
+      {"action" => "authentication_required", "message" => error.message}
+    )
   end
 
   # @param session_id [Integer] ID of the session to process
   def perform(session_id)
     session = Session.find(session_id)
+
+    # Atomic: only one job processes a session at a time. If another job
+    # is already running, this one exits — the running job will pick up
+    # any pending messages after its current loop completes.
+    return unless claim_processing(session_id)
+
     agent_loop = AgentLoop.new(session: session)
-    agent_loop.run
+    loop do
+      agent_loop.run
+      promoted = session.promote_pending_messages!
+      break if promoted == 0
+    end
   ensure
+    release_processing(session_id)
     agent_loop&.finalize
   end
 
   private
 
+  # 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)
+    Session.where(id: session_id, processing: false).update_all(processing: true) == 1
+  end
+
+  # Clears the processing flag so the session can accept new jobs.
+  def release_processing(session_id)
+    Session.where(id: session_id).update_all(processing: false)
+  end
+
   # Emits a system message before each retry so the user sees
   # "retrying..." instead of nothing.
   def retry_job(options = {})

data/app/jobs/count_event_tokens_job.rb

@@ -12,7 +12,7 @@ class CountEventTokensJob < ApplicationJob
   # @param event_id [Integer] the Event record to count tokens for
   def perform(event_id)
     event = Event.find(event_id)
-    return if event.token_count > 0
+    return if already_counted?(event)
 
     provider = Providers::Anthropic.new
     messages = [{role: event.api_role, content: event.payload["content"].to_s}]
@@ -22,7 +22,18 @@ class CountEventTokensJob < ApplicationJob
       messages: messages
     )
 
-    # Atomic update: only write if still uncounted (avoids race with parallel jobs).
-    Event.where(id: event.id, token_count: 0).update_all(token_count: token_count)
+    # Guard against parallel jobs: reload and re-check before writing.
+    # Uses update! (not update_all) so {Event::Broadcasting} after_update_commit
+    # broadcasts the updated token count to connected clients.
+    event.reload
+    return if already_counted?(event)
+
+    event.update!(token_count: token_count)
+  end
+
+  private
+
+  def already_counted?(event)
+    event.token_count > 0
   end
 end

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

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Broadcasts Event records to connected WebSocket clients via ActionCable.
+# Follows the Turbo Streams pattern: events are broadcast on both create
+# and update, with an action type so clients can distinguish append from
+# replace operations.
+#
+# Each broadcast includes the Event's database ID, enabling clients to
+# maintain an ID-indexed store for efficient in-place updates (e.g. when
+# token counts arrive asynchronously from {CountEventTokensJob}).
+#
+# @example Create broadcast payload
+#   {
+#     "type" => "user_message", "content" => "hello", ...,
+#     "id" => 42, "action" => "create",
+#     "rendered" => { "basic" => { "role" => "user", "content" => "hello" } }
+#   }
+#
+# @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 Event::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_event(action: ACTION_CREATE)
+  end
+
+  def broadcast_update
+    broadcast_event(action: ACTION_UPDATE)
+  end
+
+  # Decorates the event for the session's current view mode and broadcasts
+  # the payload to the session's ActionCable stream.
+  #
+  # @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"
+    decorator = EventDecorator.for(self)
+    broadcast_payload = payload.merge("id" => id, "action" => action)
+
+    if decorator
+      broadcast_payload["rendered"] = {mode => decorator.render(mode)}
+    end
+
+    ActionCable.server.broadcast("session_#{session_id}", broadcast_payload)
+  end
+end

data/app/models/event.rb

@@ -16,12 +16,18 @@
 # @!attribute tool_use_id
 #   @return [String, nil] Anthropic-assigned ID correlating tool_call and tool_response
 class Event < ApplicationRecord
+  include Event::Broadcasting
+
   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
+  PENDING_STATUS = "pending"
 
   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}
@@ -40,6 +46,17 @@ class Event < ApplicationRecord
   #   @return [ActiveRecord::Relation]
   scope :context_events, -> { where(event_type: CONTEXT_TYPES) }
 
+  # @!method self.pending
+  #   User messages queued during active agent processing, not yet sent to LLM.
+  #   @return [ActiveRecord::Relation]
+  scope :pending, -> { where(status: PENDING_STATUS) }
+
+  # @!method self.deliverable
+  #   Events eligible for LLM context (excludes pending messages).
+  #   NULL status means delivered/processed — the only excluded value is "pending".
+  #   @return [ActiveRecord::Relation]
+  scope :deliverable, -> { where(status: nil) }
+
   # Maps event_type to the Anthropic Messages API role.
   # @return [String] "user" or "assistant"
   def api_role
@@ -56,6 +73,25 @@ class Event < ApplicationRecord
     event_type.in?(CONTEXT_TYPES)
   end
 
+  # @return [Boolean] true if this is a pending message not yet sent to the LLM
+  def pending?
+    status == PENDING_STATUS
+  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,24 +7,38 @@ 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
 
+  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)
+  # @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)
+  def viewport_events(token_budget: DEFAULT_TOKEN_BUDGET, include_pending: true)
+    scope = events.context_events
+    scope = scope.deliverable unless include_pending
+
     selected = []
     remaining = token_budget
 
-    events.context_events.reorder(id: :desc).each do |event|
+    scope.reorder(id: :desc).each do |event|
       cost = (event.token_count > 0) ? event.token_count : estimate_tokens(event)
       break if cost > remaining && selected.any?
 
@@ -35,16 +49,40 @@ class Session < ApplicationRecord
     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.
+  # Pending messages are excluded — they haven't been delivered yet.
   #
   # @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))
+    assemble_messages(viewport_events(token_budget: token_budget, include_pending: false))
+  end
+
+  # Promotes all pending user messages to delivered status so they
+  # appear in the next LLM context. Triggers broadcast_update for
+  # each event so connected clients refresh the pending indicator.
+  #
+  # @return [Integer] number of promoted messages
+  def promote_pending_messages!
+    promoted = 0
+    events.where(event_type: "user_message", status: Event::PENDING_STATUS).find_each do |event|
+      event.update!(status: nil, payload: event.payload.except("status"))
+      promoted += 1
+    end
+    promoted
   end
 
   private
@@ -97,18 +135,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/config/application.rb

@@ -8,6 +8,7 @@ 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"
 

data/config/initializers/event_subscribers.rb

@@ -7,5 +7,4 @@ 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/routes.rb

@@ -3,10 +3,4 @@
 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/db/cable_schema.rb

@@ -1,9 +1,21 @@
+# 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.binary "payload", limit: 536870912, null: false
-    t.datetime "created_at", 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"

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

data/db/migrate/20260313010000_add_status_to_events.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+class AddStatusToEvents < ActiveRecord::Migration[8.1]
+  def change
+    add_column :events, :status, :string
+    add_index :events, [:session_id, :status], name: "index_events_on_session_id_and_status"
+  end
+end

data/db/migrate/20260313020000_add_processing_to_sessions.rb

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

data/lib/agent_loop.rb

@@ -87,11 +87,14 @@ class AgentLoop
   private
 
   # Builds the default tool registry with all available tools.
-  # @return [Tools::Registry] registry with Bash and WebGet tools
+  # @return [Tools::Registry] registry with all available tools
   def build_tool_registry
     registry = Tools::Registry.new(context: {shell_session: @shell_session})
-    registry.register(Tools::WebGet)
     registry.register(Tools::Bash)
+    registry.register(Tools::Read)
+    registry.register(Tools::Write)
+    registry.register(Tools::Edit)
+    registry.register(Tools::WebGet)
     registry
   end
 end

data/lib/anima/cli.rb

@@ -47,17 +47,13 @@ module Anima
     option :host, desc: "Brain server address (default: #{DEFAULT_HOST})"
     def tui
       require "ratatui_ruby"
-      require "net/http"
-      require "json"
       require_relative "../tui/app"
 
       host = options[:host] || DEFAULT_HOST
 
       say "Connecting to brain at #{host}...", :cyan
-      session_id = fetch_current_session_with_retry(host)
-      say "Session ##{session_id} — starting TUI", :cyan
 
-      cable_client = TUI::CableClient.new(host: host, session_id: session_id)
+      cable_client = TUI::CableClient.new(host: host)
       cable_client.connect
 
       TUI::App.new(cable_client: cable_client).run
@@ -71,40 +67,5 @@ module Anima
     end
 
     private
-
-    MAX_SESSION_FETCH_ATTEMPTS = 10
-    SESSION_FETCH_DELAY = 2 # seconds between retries
-
-    # Fetches the current session ID from the brain's REST API.
-    # Retries up to {MAX_SESSION_FETCH_ATTEMPTS} times if the brain is not running.
-    #
-    # @param host [String] brain server address
-    # @return [Integer] session ID
-    def fetch_current_session_with_retry(host)
-      attempts = 0
-      begin
-        fetch_current_session(host)
-      rescue Errno::ECONNREFUSED, Net::ReadTimeout, Net::OpenTimeout, SocketError => error
-        attempts += 1
-        if attempts >= MAX_SESSION_FETCH_ATTEMPTS
-          say "Cannot connect to brain after #{MAX_SESSION_FETCH_ATTEMPTS} attempts", :red
-          exit 1
-        end
-        say "Brain not available (#{error.class.name.split("::").last}). " \
-            "Retrying #{attempts}/#{MAX_SESSION_FETCH_ATTEMPTS}... (Ctrl+C to cancel)", :yellow
-        sleep SESSION_FETCH_DELAY
-        retry
-      end
-    end
-
-    # Fetches the current session ID from the brain's REST API.
-    # @param host [String] brain server address
-    # @return [Integer] session ID
-    # @raise [RuntimeError] if the brain returns an error response
-    def fetch_current_session(host)
-      uri = URI("http://#{host}/api/sessions/current")
-      body = Net::HTTP.get(uri)
-      JSON.parse(body)["id"]
-    end
   end
 end

data/lib/anima/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Anima
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/events/subscribers/persister.rb

@@ -42,6 +42,7 @@ module Events
           target_session.events.create!(
             event_type: event_type,
             payload: payload,
+            status: payload[:status],
             tool_use_id: payload[:tool_use_id],
             timestamp: payload[:timestamp] || Process.clock_gettime(Process::CLOCK_REALTIME, :nanosecond)
           )

data/lib/events/user_message.rb

@@ -4,8 +4,25 @@ module Events
   class UserMessage < Base
     TYPE = "user_message"
 
+    # @return [String, nil] "pending" when queued during active processing, nil otherwise
+    attr_reader :status
+
+    # @param content [String] message text
+    # @param session_id [Integer, nil] session identifier
+    # @param status [String, nil] "pending" when queued during active agent processing
+    def initialize(content:, session_id: nil, status: nil)
+      super(content: content, session_id: session_id)
+      @status = status
+    end
+
     def type
       TYPE
     end
+
+    def to_h
+      h = super
+      h[:status] = status if status
+      h
+    end
   end
 end