anima-core 0.0.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1093dd7268e23c30a34d081b91ae453080aba47f5864ed285baf3a4d637ddabe
-  data.tar.gz: c75a06cca5222689a4b204846eca8843c1ac912608dec8a8b3898443f6219728
+  metadata.gz: fcb9e1d40357cd0eabdc5fffa01f8727b449a5b85e6f7b7dbe9033fae461bec9
+  data.tar.gz: d785a36f13e3a3e698b80dd123544ca6dbee535372b92776a5b7993e4125baa1
 SHA512:
-  metadata.gz: 2e5b40e05fdd0a193adf362d4eda84d83ddfe51f379b8ebb3cc17070af733371526632946ecd577756815d10bd410e919a3013a942821ccf1f4c9fea966bfbe8
-  data.tar.gz: b28b6f7e60478e06bedeb8a87a4ce682dd65a9111007626565af515518f614e682b18bd26adb59ba6aa3d9dd1bc5c468c605229c880b4da0ad3ccdd96257e76a
+  metadata.gz: d84d91dc67fe56617f294b9a6982e830ac36c242fdb203bfa601c2e6fb009dd8a3d9d5243c4bfa501d7069e40bb08d15d920717374a79825ff1af7b4812713de
+  data.tar.gz: d61f7ed56737c02f4412bcdee5d15e9b4b8e3b63f45011aa9e8ae2c1a80725413841ad1ed95d7f02ab6a8e532e0a36f0fd9abc39b50adb5fed0dbb21ec599604

data/.reek.yml

@@ -0,0 +1,18 @@
+---
+detectors:
+  # YARD docs cover module/class documentation; no need for reek to duplicate
+  IrresponsibleModule:
+    enabled: false
+  # Constructor injection (provider: nil) triggers false positives
+  ControlParameter:
+    enabled: false
+  # Bang methods don't need safe counterparts in this codebase
+  MissingSafeMethod:
+    enabled: false
+  # Private helpers don't need instance state to be valid
+  UtilityFunction:
+    public_methods_only: true
+
+# TUI render methods receive (frame, tui) by design — RatatuiRuby convention
+exclude_paths:
+  - lib/tui

data/CHANGELOG.md

@@ -1,5 +1,41 @@
 ## [Unreleased]
 
+## [0.2.0] - 2026-03-10
+
+### Added
+- Client-server architecture — Brain (Rails + Puma) runs as persistent service, TUI connects via WebSocket
+- Action Cable infrastructure with Solid Cable adapter for Brain/TUI WebSocket communication
+- `SessionChannel` — WebSocket channel for session management, message relay, and session switching
+- Graceful TUI reconnection with exponential backoff (up to 10 attempts, max 30s delay)
+- `AgentRequestJob` — background job for LLM agent loops with retry logic for transient failures (network errors, rate limits, server errors)
+- Provider error hierarchy — `TransientError`, `RateLimitError`, `ServerError` for retry classification; `AuthenticationError` for immediate discard
+- `AgentLoop#run` — retry-safe entry point for job callers; lets errors propagate for external retry handling
+- `AgentLoop` service — decouples LLM orchestration from TUI; callable from background jobs, Action Cable channels, or TUI directly
+- Session and event persistence to SQLite — conversations survive TUI restart
+- `Session` model — owns an ordered event stream
+- `Event` model — polymorphic type, JSON payload, auto-incrementing position
+- `Events::Subscribers::Persister` — writes all events to SQLite as they flow through the bus
+- TUI resumes last session on startup, `Ctrl+a > n` creates a new session
+- Event system using Rails Structured Event Reporter (`Rails.event`)
+- Five event types: `system_message`, `user_message`, `agent_message`, `tool_call`, `tool_response`
+- `Events::Bus` — thin wrapper around `Rails.event` for emitting and subscribing to Anima events
+- `Events::Subscribers::MessageCollector` — in-memory subscriber that collects displayable messages
+- Chat screen refactored from raw array to event-driven architecture
+- TUI chat screen with LLM integration — in-memory message array, threaded API calls
+- Chat input with character validation, backspace, Enter to submit
+- Loading indicator — "Thinking" status bar mode, grayed-out input during LLM calls
+- New session command (`Ctrl+a > n`) clears conversation
+- Error handling — API failures displayed inline as chat messages
+- Anthropic API subscription token authentication
+- LLM client (raw HTTP to Anthropic API)
+- TUI scaffold with RatatuiRuby — tmux-style `Ctrl+a` command mode, sidebar, status bar
+- Headless Rails 8.1 app (API-only, no views/assets)
+- `anima install` command — creates ~/.anima/ tree, per-environment credentials, systemd user service
+- `anima start` command — runs db:prepare and boots Rails via Foreman
+- Systemd user service — auto-enables and starts brain on `anima install`
+- SQLite databases, logs, tmp, and credentials stored in ~/.anima/
+- Environment validation (development, test, production)
+
 ## [0.0.1] - 2026-03-06
 
 - Initial gem scaffold with CI and RubyGems publishing

data/Gemfile

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in anima-core.gemspec
+gemspec
+
+gem "irb"
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"
+gem "rspec-rails", "~> 7.0"
+
+gem "reek", "~> 6.5"
+gem "standard", "~> 1.3"
+
+gem "webmock", "~> 3.23"

data/Procfile

@@ -0,0 +1,2 @@
+web: bin/rails server
+worker: bin/jobs

data/Procfile.dev

@@ -0,0 +1,2 @@
+web: bin/rails server
+worker: bin/jobs

data/README.md

@@ -1,9 +1,8 @@
-# Anima Framework
+# Anima
 
-**A soul engine for AI agents.**
+**A personal AI agent that actually wants things.**
 
-Ruby framework for building AI agents with desires, personality, and personal growth.
-Powered by [Rage](https://rage-rb.dev/).
+Your agent. Your machine. Your rules. Anima is an AI agent with desires, personality, and personal growth — running locally as a headless Rails 8.1 app with a client-server architecture and TUI interface.
 
 ## The Problem
 
@@ -61,26 +60,141 @@ Existing RL techniques apply at the starting point, then we gradually expand int
 ## Architecture
 
 ```
-Anima Framework (Ruby, Rage-based)
+Anima (Ruby, Rails 8.1 headless)
 ├── Thymos    — hormonal/desire system (stimulus → hormone vector)
 ├── Mneme     — semantic memory (QMD-style, emotional recall)
 ├── Psyche    — soul matrix (coefficient table, evolving through experience)
 └── Nous      — LLM integration (cortex, thinking, decision-making)
 ```
 
+### Runtime Architecture
+
+Anima runs as a client-server system:
+
+```
+Brain Server (Rails + Puma)              TUI Client (RatatuiRuby)
+├── LLM integration (Anthropic)          ├── WebSocket client
+├── Agent loop + tool execution          ├── Terminal rendering
+├── Event bus + persistence              └── User input capture
+├── Solid Queue (background jobs)
+├── Action Cable (WebSocket server)
+└── SQLite databases                ◄── WebSocket (port 42134) ──► TUI
+```
+
+The **Brain** is the persistent service — it handles LLM calls, tool execution, event processing, and state. The **TUI** is a stateless client — it connects via WebSocket, renders events, and captures input. If TUI disconnects, the brain keeps running. TUI reconnects automatically with exponential backoff and resumes the session with chat history preserved.
+
+### Tech Stack
+
+| Component | Technology |
+|-----------|-----------|
+| Framework | Rails 8.1 (headless — no web views, no asset pipeline) |
+| Database | SQLite (3 databases per environment: primary, queue, cable) |
+| Event system | Rails Structured Event Reporter + Action Cable bridge |
+| LLM integration | Anthropic API (Claude Sonnet 4) |
+| Transport | Action Cable WebSocket (Solid Cable adapter) |
+| Background jobs | Solid Queue |
+| Interface | TUI via RatatuiRuby (WebSocket client) |
+| Process management | Foreman |
+| Distribution | RubyGems (`gem install anima-core`) |
+
+### Distribution Model
+
+Anima is a Rails app distributed as a gem, following Unix philosophy: immutable program separate from mutable data.
+
+```bash
+gem install anima-core       # Install the Rails app as a gem
+anima install                # Create ~/.anima/, set up databases, start brain as systemd service
+anima tui                    # Connect the terminal interface
+```
+
+The installer creates a systemd user service that starts the brain automatically on login. Manage it with:
+
+```bash
+systemctl --user status anima    # Check brain status
+systemctl --user restart anima   # Restart brain
+journalctl --user -u anima       # View logs
+```
+
+State directory (`~/.anima/`):
+```
+~/.anima/
+├── db/              # SQLite databases (production, development, test)
+├── config/
+│   ├── credentials/ # Rails encrypted credentials per environment
+│   └── anima.yml    # User configuration
+├── log/
+└── tmp/
+```
+
+Updates: `gem update anima-core` — next launch runs pending migrations automatically.
+
+### Authentication Setup
+
+Anima uses your Claude Pro/Max subscription for API access. You need a setup-token from Claude Code CLI.
+
+**1. Get a setup-token:**
+
+```bash
+claude setup-token
+```
+
+This requires [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) installed and a Claude Pro or Max subscription.
+
+**2. Store the token in Anima credentials:**
+
+```bash
+cd $(gem contents anima-core | head -1 | xargs dirname | xargs dirname)
+bin/rails credentials:edit
+```
+
+Add your token:
+
+```yaml
+anthropic:
+  subscription_token: sk-ant-oat01-YOUR_TOKEN_HERE
+```
+
+**3. Verify the token works:**
+
+```bash
+bin/rails runner "Providers::Anthropic.validate!"
+```
+
+If the token expires or is revoked, repeat steps 1-2 with a new token.
+
 ### Three Layers (mirroring biology)
 
 1. **Endocrine system (Thymos)** — a lightweight background process. Reads recent events. Doesn't respond. Just updates hormone levels. Pure stimulus→response, like a biological gland.
 
-2. **Homeostasis** — persistent state (JSON/SQLite). Current hormone levels with decay functions. No intelligence, just state that changes over time.
+2. **Homeostasis** — persistent state (SQLite). Current hormone levels with decay functions. No intelligence, just state that changes over time.
 
 3. **Cortex (Nous)** — the main LLM. Reads hormone state transformed into **desire descriptions**. Not "longing: 87" but "you want to see them". The LLM should NOT see raw numbers — humans don't see cortisol levels, they feel anxiety.
 
 ### Event-Driven Design
 
-Built on [Rage](https://rage-rb.dev/) — a Ruby framework with fiber-based concurrency, native WebSockets, and a built-in event bus. The event bus maps directly to a nervous system: stimuli fire events, Thymos subscribers update hormone levels, Nous reacts to the resulting desires.
+Built on Rails Structured Event Reporter — a native Rails 8.1 feature for structured event emission with typed payloads, subscriber patterns, and block-scoped context tagging.
+
+Five event types form the agent's nervous system:
+
+| Event | Purpose |
+|-------|---------|
+| `system_message` | Internal notifications |
+| `user_message` | User input |
+| `agent_message` | LLM response |
+| `tool_call` | Tool invocation |
+| `tool_response` | Tool result |
 
-Single-process architecture: web server, background hormone ticks, WebSocket monitoring — all in one process, no Redis, no external workers.
+Events flow through two channels:
+1. **In-process** — Rails Structured Event Reporter (local subscribers like Persister)
+2. **Over the wire** — Action Cable WebSocket (the ActionCableBridge subscriber forwards events to connected TUI clients)
+
+Events fire, subscribers react, state updates, the cortex (LLM) reads the resulting desire landscape. The system prompt is assembled separately for each LLM call — it is not an event.
+
+### Context as Viewport, Not Tape
+
+There is no linear chat history. There are only events attached to a session. The context window is a **viewport** — a sliding window over the event stream, assembled on demand for each LLM call within a configured token budget.
+
+Currently uses a simple sliding window (newest events first, walk backwards until budget exhausted). Future versions will add multi-resolution compression with Draper decorators and associative recall from Mneme.
 
 ### Brain as Microservices on a Shared Event Bus
 
@@ -95,7 +209,7 @@ Event: "tool_call_failed"
   ├── Mneme subscriber: log failure context for future recall
   └── Psyche subscriber: update coefficient (this agent handles errors calmly → low frustration_gain)
 
-Event: "user_sent_message"  
+Event: "user_sent_message"
   │
   ├── Thymos subscriber: oxytocin += 5 (bonding signal)
   ├── Thymos subscriber: dopamine += 3 (engagement signal)
@@ -104,7 +218,17 @@ Event: "user_sent_message"
 
 Each subscriber is a microservice — independent, stateless, reacting to the same event bus. No orchestrator decides "now update frustration." The architecture IS the nervous system.
 
-This is why Rage's built-in event bus maps so naturally: `Rage.event_bus` IS the nervous system. Events fire, subscribers react, state updates, the cortex (LLM) reads the resulting desire landscape.
+### Plugin Architecture
+
+Both tools and feelings are distributed as gems on the event bus:
+
+```bash
+anima add anima-tools-filesystem
+anima add anima-tools-shell
+anima add anima-feelings-frustration
+```
+
+Tools provide MCP capabilities. Feelings are event subscribers that update hormonal state. Same mechanism, different namespace. Currently tools are built-in; plugin extraction comes later.
 
 ### Semantic Memory (Mneme)
 
@@ -207,17 +331,38 @@ This single example demonstrates every core principle:
 
 ## Status
 
-Idea stage → early design. Architecture research underway (OpenClaw agent loop documented).
-First practical hormone (frustration) designed, ready for prototyping.
+**Core agent complete.** The conversational agent works end-to-end: event-driven architecture, LLM integration with tool calling (bash, web), sliding viewport context assembly, persistent sessions, and client-server architecture with WebSocket transport and graceful reconnection.
+
+The hormonal system (Thymos, feelings, desires), semantic memory (Mneme), and soul matrix (Psyche) are designed but not yet implemented — they're the next layer on top of the working agent.
+
+## Development
+
+```bash
+git clone https://github.com/hoblin/anima.git
+cd anima
+bin/setup
+```
+
+### Running Anima
+
+Start the brain server and TUI client in separate terminals:
+
+```bash
+# Terminal 1: Start brain (web server + background worker) on port 42135
+bin/dev
+
+# Terminal 2: Connect the TUI to the dev brain
+bundle exec anima tui --host localhost:42135
+```
+
+Development uses port **42135** so it doesn't conflict with the production brain (port 42134) running via systemd. On first run, `bin/dev` runs `db:prepare` automatically.
+
+### Running Tests
+
+```bash
+bundle exec rspec
+```
 
-## Next Steps
+## License
 
-- [ ] **MVP: Frustration hormone** — monitor tool calls, adjust thinking budget + inner voice injection
-- [ ] Research prior art in depth (affective computing, BDI architecture, virtual creature motivation)
-- [ ] Design initial coefficient matrix schema (Psyche)
-- [ ] Prototype Thymos: Rage event bus + JSON state + context injection into LLM thinking step
-- [ ] Experiment: hormone names vs abstract parameter names in LLM prompts
-- [ ] Set up Rage project skeleton with event bus
-- [ ] Design full event taxonomy (what events does the agent's "nervous system" react to?)
-- [ ] Build Mneme: semantic memory with emotional associations
-- [ ] Write blog post introducing the concept
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/Rakefile

@@ -1,10 +1,25 @@
 # frozen_string_literal: true
 
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+require_relative "config/application"
+Rails.application.load_tasks
 
-RSpec::Core::RakeTask.new(:spec)
+begin
+  require "bundler/gem_tasks"
+rescue LoadError
+  # bundler not available in gem install context
+end
 
-require "standard/rake"
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+  # rspec not available in gem install context
+end
 
-task default: %i[spec standard]
+begin
+  require "standard/rake"
+rescue LoadError
+  # standard not available in gem install context
+end
+
+task default: %i[spec standard] if Rake::Task.task_defined?(:spec) && Rake::Task.task_defined?(:standard)

data/anima-core.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/anima/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "anima-core"
+  spec.version = Anima::VERSION
+  spec.authors = ["Yevhenii Hurin"]
+  spec.email = ["evgeny.gurin@gmail.com"]
+
+  spec.summary = "A personal AI agent with desires, personality, and personal growth"
+  spec.homepage = "https://github.com/hoblin/anima"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.2.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/hoblin/anima"
+  spec.metadata["changelog_uri"] = "https://github.com/hoblin/anima/blob/main/CHANGELOG.md"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls|
+    ls.readlines("\x0", chomp: true).reject do |f|
+      f.start_with?(*%w[bin/console bin/dev bin/setup .gitignore .rspec spec/ .github/ .standard.yml thoughts/ CLAUDE.md])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "foreman", "~> 0.88"
+  spec.add_dependency "httparty", "~> 0.24"
+  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 "websocket-client-simple", "~> 0.8"
+end

data/app/channels/application_cable/channel.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ApplicationCable
+  class Channel < ActionCable::Channel::Base
+  end
+end

data/app/channels/application_cable/connection.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ApplicationCable
+  class Connection < ActionCable::Connection::Base
+  end
+end

data/app/channels/session_channel.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+# Streams events for a specific session to connected clients.
+# Part of the Brain/TUI separation: the Brain broadcasts events through
+# this channel, and any number of clients (TUI, web, API) can subscribe.
+#
+# On subscription, sends the session's chat history so the client can
+# render previous messages without a separate API call.
+#
+# @example Client subscribes to a session
+#   App.cable.subscriptions.create({ channel: "SessionChannel", session_id: 42 })
+class SessionChannel < ApplicationCable::Channel
+  DEFAULT_LIST_LIMIT = 10
+  MAX_LIST_LIMIT = 50
+
+  # Subscribes the client to the session-specific stream.
+  # Rejects the subscription if no valid session_id is provided.
+  # Transmits chat history to the subscribing client after confirmation.
+  #
+  # @param params [Hash] must include :session_id (positive integer)
+  def subscribed
+    @current_session_id = params[:session_id].to_i
+    if @current_session_id > 0
+      stream_from stream_name
+      transmit_history
+    else
+      reject
+    end
+  end
+
+  # Receives messages from clients and broadcasts them to all session subscribers.
+  #
+  # @param data [Hash] arbitrary message payload
+  def receive(data)
+    ActionCable.server.broadcast(stream_name, data)
+  end
+
+  # Processes user input: persists the message and enqueues LLM processing.
+  #
+  # @param data [Hash] must include "content" with the user's message text
+  def speak(data)
+    content = data["content"].to_s.strip
+    return if content.empty? || !Session.exists?(@current_session_id)
+
+    Events::Bus.emit(Events::UserMessage.new(content: content, session_id: @current_session_id))
+    AgentRequestJob.perform_later(@current_session_id)
+  end
+
+  # Returns recent sessions with metadata for session picker UI.
+  #
+  # @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
+
+    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
+    transmit({"action" => "sessions_list", "sessions" => result})
+  end
+
+  # Creates a new session and switches the channel stream to it.
+  # The client receives a session_changed signal followed by (empty) history.
+  def create_session(_data)
+    session = Session.create!
+    switch_to_session(session.id)
+  end
+
+  # Switches the channel stream to an existing session.
+  # The client receives a session_changed signal followed by chat history.
+  #
+  # @param data [Hash] must include "session_id" (positive integer)
+  def switch_session(data)
+    target_id = data["session_id"].to_i
+    return transmit_error("Session not found") unless target_id > 0
+
+    switch_to_session(target_id)
+  rescue ActiveRecord::RecordNotFound
+    transmit_error("Session not found")
+  end
+
+  private
+
+  def stream_name
+    "session_#{@current_session_id}"
+  end
+
+  # Switches the channel to a different session: stops current stream,
+  # updates the session reference, starts the new stream, and sends
+  # a session_changed signal followed by chat history.
+  def switch_to_session(new_id)
+    stop_all_streams
+    @current_session_id = new_id
+    stream_from stream_name
+    session = Session.find(new_id)
+    transmit({
+      "action" => "session_changed",
+      "session_id" => new_id,
+      "message_count" => session.events.llm_messages.count
+    })
+    transmit_history
+  end
+
+  # Sends displayable events from the LLM's viewport to the subscribing
+  # client. The TUI shows exactly what the agent can see — no more, no less.
+  def transmit_history
+    session = Session.find_by(id: @current_session_id)
+    return unless session
+
+    session.viewport_events.each do |event|
+      next unless event.llm_message?
+
+      transmit(event.payload)
+    end
+  end
+
+  def transmit_error(message)
+    transmit({"action" => "error", "message" => message})
+  end
+end

data/app/controllers/api/sessions_controller.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Api
+  # REST endpoint for session management. The TUI client uses this to
+  # obtain a session ID before subscribing to the WebSocket channel.
+  class SessionsController < ApplicationController
+    # Returns the most recent session or creates one if none exist.
+    #
+    # GET /api/sessions/current
+    # @return [JSON] { id: Integer }
+    def current
+      session = Session.last || Session.create!
+      render json: {id: session.id}
+    end
+
+    # Creates a new conversation session.
+    #
+    # POST /api/sessions
+    # @return [JSON] { id: Integer }
+    def create
+      session = Session.create!
+      render json: {id: session.id}, status: :created
+    end
+  end
+end

data/app/controllers/application_controller.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class ApplicationController < ActionController::API
+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/application_job.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+class ApplicationJob < ActiveJob::Base
+end