anima-core 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f7039906ee15401ed13db1ceaa640b088540903b1f0b814463fe69d91f6fa02
-  data.tar.gz: dee3280a42efa74aa78b3499f8c6687a937287eda9099e2b7de09d4ccf761021
+  metadata.gz: 9517757f2c4fdb8b19d204a154d3badd3c3b8fb456dffaf03236b2d7c065378d
+  data.tar.gz: a0d26e0b27fd1d2df0c46c3a4bbad822ac3517d1d02b41a6bdd49195de64e71f
 SHA512:
-  metadata.gz: 1ed4a8551e9ba05919e95a4879bf2366e9cd4986726ebe0ed5900007bd6d06a53639133be5a286d38e41a7f269db78b3575ff982c23d2b4096f804c3528b02a0
-  data.tar.gz: 65f6d5dbe475dd36af817a3f2eb88c6f6913604de6bfc9dd56775d18abf8e47e0269862e669a8f739ee57fa99a9aede77d343c692400a44a4e873d28ee482c7a
+  metadata.gz: d150e5f97a3a2055c66cfaa773c7bd1dd33354b869fe38d6fa25b2b47352c76cec0c222f44aa4eb7e7e65b61098b7531e61522a01e6dd1d722ee9224c7759aea
+  data.tar.gz: 0f9ef56323a4598ed8dc3dca79e6ec9cf1e63ea9dff8751612cd32691aa0968e629144b4f7c47150cd9c9861f3d74e323c852433e1aa066732bb10fc8db235fc

data/CHANGELOG.md

@@ -1,12 +1,40 @@
 ## [Unreleased]
 
+## [0.2.1] - 2026-03-13
+
+### Added
+- TUI view mode switching via `Ctrl+a → v` — cycle between Basic, Verbose, and Debug (#75)
+- Draper EventDecorator hierarchy — structured data decorators for all event types (#74)
+- Decorators return structured hashes (not strings) for transport-layer filtering (#86)
+- Basic mode tool call counter — inline `🔧 Tools: X/Y ✓` aggregation (#73)
+- Verbose view mode rendering — timestamps, tool call previews, system messages (#76)
+- Tool call previews: bash `$ command`, web_get `GET url`, generic JSON fallback
+- Tool response display: truncated to 3 lines, `↩` success / `❌` failure indicators
+- Debug view mode — token counts per message, full tool args/responses, tool use IDs (#77)
+- Estimated token indicator (`~` prefix) for events not yet counted by background job
+- View mode persisted on Session model — survives TUI disconnect/reconnect
+- Mode changes broadcast to all connected clients with re-decorated viewport
+
+### Fixed
+- Newlines in LLM responses collapsed into single line in rendered view modes
+- Loading state stuck after view mode switch — input blocked with "Thinking..."
+
+## [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
-- `anima tui` now runs pending migrations automatically on launch
 - 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
@@ -20,9 +48,10 @@
 - 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/Action Cable)
+- 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
+- `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)
 

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.
-Headless Rails 8.1 app distributed as a gem, with a TUI-first interface via RatatuiRuby.
+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,22 +60,41 @@ Existing RL techniques apply at the starting point, then we gradually expand int
 ## Architecture
 
 ```
-Anima Framework (Ruby, Rails 8.1 headless)
+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 (per environment, stored in `~/.anima/db/`) |
-| Event system | Rails Structured Event Reporter |
-| LLM integration | Raw HTTP to Anthropic API |
-| Interface | TUI via RatatuiRuby |
+| 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
@@ -85,8 +103,16 @@ Anima is a Rails app distributed as a gem, following Unix philosophy: immutable
 
 ```bash
 gem install anima-core       # Install the Rails app as a gem
-anima install                # Create ~/.anima/ directory structure
-anima start                  # Launch — code from gem, state from ~/.anima/
+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/`):
@@ -158,13 +184,29 @@ Five event types form the agent's nervous system:
 | `tool_call` | Tool invocation |
 | `tool_response` | Tool result |
 
+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.
 
-POC 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.
+Currently uses a simple sliding window (newest events first, walk backwards until budget exhausted). Future versions will add associative recall from Mneme.
+
+### TUI View Modes
+
+Three switchable view modes let you control how much detail the TUI shows. Cycle with `Ctrl+a → v`:
+
+| Mode | What you see |
+|------|-------------|
+| **Basic** (default) | User + assistant messages. Tool calls are hidden but summarized as an inline counter: `🔧 Tools: 2/2 ✓` |
+| **Verbose** | Everything in Basic, plus timestamps `[HH:MM:SS]`, tool call previews (`🔧 bash` / `$ command` / `↩ response`), and system messages |
+| **Debug** | Full X-ray view — timestamps, token counts per message (`[14 tok]`), full tool call args, full tool responses, tool use IDs |
+
+View modes are implemented via Draper decorators that operate at the transport layer. Each event type has a dedicated decorator (`UserMessageDecorator`, `ToolCallDecorator`, etc.) that returns structured data — the TUI renders it. Mode is stored on the `Session` model server-side, so it persists across reconnections.
 
 ### Brain as Microservices on a Shared Event Bus
 
@@ -198,7 +240,7 @@ 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. In POC, tools are built-in; plugin extraction comes later.
+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)
 
@@ -301,36 +343,36 @@ This single example demonstrates every core principle:
 
 ## Status
 
-POC stage. Gem scaffold with CI and RubyGems publishing exists. Building toward a working conversational agent with event-driven architecture.
+**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, client-server architecture with WebSocket transport, graceful reconnection, and three TUI view modes (Basic/Verbose/Debug) via Draper decorators.
 
-The hormonal system (Thymos, feelings, desires), semantic memory (Mneme), and soul matrix (Psyche) are designed but deferred — POC focuses on getting the core agent loop working first.
+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
-bundle install
-bundle exec rspec
+bin/setup
 ```
 
-### Running the TUI
+### Running Anima
 
-The TUI requires a background job worker for async token counting (used by the sliding viewport). Start both in separate terminals:
+Start the brain server and TUI client in separate terminals:
 
 ```bash
-# Terminal 1: Start Solid Queue worker
-RAILS_ENV=development bundle exec rake solid_queue:start
+# Terminal 1: Start brain (web server + background worker) on port 42135
+bin/dev
 
-# Terminal 2: Launch the TUI
-bundle exec anima tui
+# Terminal 2: Connect the TUI to the dev brain
+bundle exec anima tui --host localhost:42135
 ```
 
-On first run, initialize the databases:
+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
-RAILS_ENV=development bundle exec rails db:migrate
-RAILS_ENV=development bundle exec rails db:schema:load:queue
+bundle exec rspec
 ```
 
 ## License

data/Rakefile

@@ -1,13 +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
 
-require_relative "config/application"
-Rails.application.load_tasks
+begin
+  require "standard/rake"
+rescue LoadError
+  # standard not available in gem install context
+end
 
-task default: %i[spec standard]
+task default: %i[spec standard] if Rake::Task.task_defined?(:spec) && Rake::Task.task_defined?(:standard)

data/anima-core.gemspec

@@ -0,0 +1,41 @@
+# 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 "draper", "~> 4.0"
+  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,218 @@
+# 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 the current view_mode and chat history to the subscribing client.
+  #
+  # @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_view_mode
+      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
+
+  # Changes the session's view mode and re-broadcasts the viewport.
+  # All clients on the session receive the mode change and fresh history.
+  #
+  # @param data [Hash] must include "view_mode" (one of Session::VIEW_MODES)
+  def change_view_mode(data)
+    mode = data["view_mode"].to_s
+    return transmit_error("Invalid view mode") unless Session::VIEW_MODES.include?(mode)
+
+    session = Session.find(@current_session_id)
+    session.update!(view_mode: mode)
+
+    ActionCable.server.broadcast(stream_name, {"action" => "view_mode_changed", "view_mode" => mode})
+    broadcast_viewport(session)
+  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,
+      "view_mode" => session.view_mode
+    })
+    transmit_history
+  end
+
+  # Transmits the current view_mode so the TUI initializes correctly.
+  # Sends `{action: "view_mode", view_mode: <mode>}` to the subscribing client.
+  # @return [void]
+  def transmit_view_mode
+    session = Session.find_by(id: @current_session_id)
+    return unless session
+
+    transmit({"action" => "view_mode", "view_mode" => session.view_mode})
+  end
+
+  # Sends decorated context events (messages + tool interactions) from
+  # the LLM's viewport to the subscribing client. Each event is wrapped
+  # in an {EventDecorator} and the pre-rendered output is included in
+  # the transmitted payload. Tool events are included so the TUI can
+  # reconstruct tool call counters on reconnect.
+  # In debug mode, prepends the assembled system prompt as a special block.
+  def transmit_history
+    session = Session.find_by(id: @current_session_id)
+    return unless session
+
+    transmit_system_prompt(session) if session.view_mode == "debug"
+
+    session.viewport_events.each do |event|
+      transmit(decorate_event_payload(event, session.view_mode))
+    end
+  end
+
+  # Broadcasts the re-decorated viewport to all clients on the session stream.
+  # Used after a view mode change to refresh all connected clients.
+  # In debug mode, prepends the assembled system prompt as a special block.
+  # @param session [Session] the session whose viewport to broadcast
+  # @return [void]
+  def broadcast_viewport(session)
+    broadcast_system_prompt(session) if session.view_mode == "debug"
+
+    session.viewport_events.each do |event|
+      ActionCable.server.broadcast(stream_name, decorate_event_payload(event, session.view_mode))
+    end
+  end
+
+  def decorate_event_payload(event, mode = "basic")
+    payload = event.payload
+    decorator = EventDecorator.for(event)
+    return payload unless decorator
+
+    payload.merge("rendered" => {mode => decorator.render(mode)})
+  end
+
+  # Transmits the assembled system prompt to the subscribing client.
+  # Skipped when the session has no system prompt configured.
+  # @param session [Session]
+  # @return [void]
+  def transmit_system_prompt(session)
+    payload = system_prompt_payload(session)
+    return unless payload
+
+    transmit(payload)
+  end
+
+  # Broadcasts the assembled system prompt to all clients on the stream.
+  # Skipped when the session has no system prompt configured.
+  # @param session [Session]
+  # @return [void]
+  def broadcast_system_prompt(session)
+    payload = system_prompt_payload(session)
+    return unless payload
+
+    ActionCable.server.broadcast(stream_name, payload)
+  end
+
+  # Builds the system prompt payload for debug mode transmission.
+  # @param session [Session]
+  # @return [Hash, nil] the system prompt payload, or nil if no prompt
+  def system_prompt_payload(session)
+    prompt = session.system_prompt
+    return unless prompt
+
+    tokens = [(prompt.bytesize / Event::BYTES_PER_TOKEN.to_f).ceil, 1].max
+    {
+      "type" => "system_prompt",
+      "rendered" => {
+        "debug" => {role: :system_prompt, content: prompt, tokens: tokens, estimated: true}
+      }
+    }
+  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/decorators/agent_message_decorator.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Decorates agent_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 AgentMessageDecorator < EventDecorator
+  # @return [Hash] structured agent message data
+  #   `{role: :assistant, content: String}`
+  def render_basic
+    {role: :assistant, content: content}
+  end
+
+  # @return [Hash] structured agent message with nanosecond timestamp
+  #   `{role: :assistant, content: String, timestamp: Integer|nil}`
+  def render_verbose
+    {role: :assistant, content: content, timestamp: timestamp}
+  end
+
+  # @return [Hash] verbose output plus token count for debugging
+  #   `{role: :assistant, content: String, timestamp: Integer|nil, tokens: Integer, estimated: Boolean}`
+  def render_debug
+    render_verbose.merge(token_info)
+  end
+end

data/app/decorators/application_decorator.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Base decorator for the application. All Draper decorators inherit from
+# this class to share common configuration and helpers.
+class ApplicationDecorator < Draper::Decorator
+end