anima-core 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcb9e1d40357cd0eabdc5fffa01f8727b449a5b85e6f7b7dbe9033fae461bec9
-  data.tar.gz: d785a36f13e3a3e698b80dd123544ca6dbee535372b92776a5b7993e4125baa1
+  metadata.gz: e3b4a76568897bb6c9d465151e61f6dd889c42c33b71dcf0c019ae561143b2e4
+  data.tar.gz: 44acf306c750f33b3bb006c7be209ec80924521f61a89d2e863179672f33751b
 SHA512:
-  metadata.gz: d84d91dc67fe56617f294b9a6982e830ac36c242fdb203bfa601c2e6fb009dd8a3d9d5243c4bfa501d7069e40bb08d15d920717374a79825ff1af7b4812713de
-  data.tar.gz: d61f7ed56737c02f4412bcdee5d15e9b4b8e3b63f45011aa9e8ae2c1a80725413841ad1ed95d7f02ab6a8e532e0a36f0fd9abc39b50adb5fed0dbb21ec599604
+  metadata.gz: bb66a71439efafa605eb7e6124269e82a0183c3d133d7e63658a1bdbe1c4f6adc9a4bf3303fb4bc724337319434eded5de40e9134c456ecbb3bb4508500b9370
+  data.tar.gz: b06ae76628e9abd1a76832703bc1769f24ea206c39c86b5fc1ef3bcfe9a59cfe87db222042aa7ea277714d18c3fb9c7c460769974fd75edd3b1f00923560e756

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 ## [Unreleased]
 
+### Added
+- Real-time event broadcasting via `Event::Broadcasting` concern — `after_create_commit` and `after_update_commit` callbacks broadcast decorated payloads with database ID and action type to the session's ActionCable stream (#91)
+- TUI `MessageStore` ID-indexed updates — events with `action: "update"` replace existing entries in-place (O(1) lookup) without changing display order
+- `CountEventTokensJob` triggers broadcast — uses `update!` so token count updates push to connected clients in real time
+- Connection status constants in `CableClient` — replaces magic strings with named constants for protocol message types
+
+### Changed
+- Connection status indicator simplified — emoji-only `🟢` for normal state, descriptive text only for abnormal states (#80)
+- `STATUS_STYLES` structure simplified from `{label, fg, bg}` to `{label, color}` (#80)
+- `ActionCableBridge` removed — broadcasting moved from EventBus subscriber to AR callbacks, eliminating the timing gap where events were broadcast before persistence
+- `SessionChannel` history includes event IDs for client-side correlation
+
+### Fixed
+- TUI showed empty chat on reconnect — message store was cleared _after_ history arrived because `confirm_subscription` comes after `transmit` in Action Cable protocol; now clears on "subscribing" before history (#82)
+
+## [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

data/README.md

@@ -130,37 +130,13 @@ Updates: `gem update anima-core` — next launch runs pending migrations automat
 
 ### Authentication Setup
 
-Anima uses your Claude Pro/Max subscription for API access. You need a setup-token from Claude Code CLI.
+Anima uses your Claude Pro/Max subscription for API access. You need a setup-token from [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code).
 
-**1. Get a setup-token:**
+1. Run `claude setup-token` in a terminal to get your token
+2. In the TUI, press `Ctrl+a → a` to open the token setup popup
+3. Paste the token and press Enter — Anima validates it against the Anthropic API and saves it to encrypted credentials
 
-```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.
+The popup also activates automatically when Anima detects a missing or invalid token. If the token expires, repeat the process with a new one.
 
 ### Three Layers (mirroring biology)
 
@@ -186,7 +162,7 @@ Five event types form the agent's nervous system:
 
 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)
+2. **Over the wire** — Action Cable WebSocket (`Event::Broadcasting` callbacks push 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.
 
@@ -194,7 +170,19 @@ Events fire, subscribers react, state updates, the cortex (LLM) reads the result
 
 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.
+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
 
@@ -331,7 +319,7 @@ This single example demonstrates every core principle:
 
 ## Status
 
-**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.
+**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 not yet implemented — they're the next layer on top of the working agent.
 

data/anima-core.gemspec

@@ -28,6 +28,7 @@ Gem::Specification.new do |spec|
   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"

data/app/channels/session_channel.rb

@@ -14,18 +14,25 @@ class SessionChannel < ApplicationCable::Channel
   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.
+  # When a valid session_id is provided, subscribes to that session.
+  # When omitted or zero, resolves to the most recent session (creating
+  # one if none exist) — this is the CQRS-compliant path where the
+  # server owns session resolution instead of a REST endpoint.
   #
-  # @param params [Hash] must include :session_id (positive integer)
+  # Always transmits a session_changed signal so the client learns
+  # the authoritative session ID, followed by view_mode and history.
+  #
+  # @param params [Hash] optional :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
+    @current_session_id = resolve_session_id
+    stream_from stream_name
+
+    session = Session.find_by(id: @current_session_id)
+    return unless session
+
+    transmit_session_changed(session)
+    transmit_view_mode(session)
+    transmit_history(session)
   end
 
   # Receives messages from clients and broadcasts them to all session subscribers.
@@ -36,14 +43,43 @@ class SessionChannel < ApplicationCable::Channel
   end
 
   # Processes user input: persists the message and enqueues LLM processing.
+  # When the session is actively processing an agent request, the message
+  # is queued as "pending" and picked up after the current loop completes.
   #
   # @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)
+    return if content.empty?
+
+    session = Session.find_by(id: @current_session_id)
+    return unless session
+
+    if session.processing?
+      Events::Bus.emit(Events::UserMessage.new(content: content, session_id: @current_session_id, status: Event::PENDING_STATUS))
+    else
+      Events::Bus.emit(Events::UserMessage.new(content: content, session_id: @current_session_id))
+      AgentRequestJob.perform_later(@current_session_id)
+    end
+  end
+
+  # Recalls the most recent pending message for editing. Deletes the
+  # pending event and broadcasts the recall so all clients remove it.
+  #
+  # @param data [Hash] must include "event_id" (positive integer)
+  def recall_pending(data)
+    event_id = data["event_id"].to_i
+    return if event_id <= 0
+
+    event = Event.find_by(
+      id: event_id,
+      session_id: @current_session_id,
+      event_type: "user_message",
+      status: Event::PENDING_STATUS
+    )
+    return unless event
 
-    Events::Bus.emit(Events::UserMessage.new(content: content, session_id: @current_session_id))
-    AgentRequestJob.perform_later(@current_session_id)
+    event.destroy!
+    ActionCable.server.broadcast(stream_name, {"action" => "user_message_recalled", "event_id" => event_id})
   end
 
   # Returns recent sessions with metadata for session picker UI.
@@ -85,12 +121,73 @@ class SessionChannel < ApplicationCable::Channel
     transmit_error("Session not found")
   end
 
+  # Validates and saves an Anthropic subscription token to encrypted credentials.
+  # Format-validated and API-validated before storage. The token never enters the
+  # LLM context window — it flows directly from WebSocket to encrypted credentials.
+  #
+  # @param data [Hash] must include "token" (Anthropic subscription token string)
+  def save_token(data)
+    token = data["token"].to_s.strip
+
+    Providers::Anthropic.validate_token_format!(token)
+    Providers::Anthropic.validate_token_api!(token)
+    write_anthropic_token(token)
+
+    transmit({"action" => "token_saved"})
+  rescue Providers::Anthropic::TokenFormatError, Providers::Anthropic::AuthenticationError => error
+    transmit({"action" => "token_error", "message" => error.message})
+  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
 
+  # Resolves the session to subscribe to. Uses the client-provided ID
+  # when valid, otherwise falls back to the most recent session or
+  # creates a new one.
+  #
+  # @return [Integer] resolved session ID
+  def resolve_session_id
+    id = params[:session_id].to_i
+    return id if id > 0
+
+    (Session.recent(1).first || Session.create!).id
+  end
+
+  # Transmits session metadata as a session_changed signal.
+  # Used on initial subscription and after session switches so the
+  # client can handle both paths with a single code path.
+  #
+  # @param session [Session] the session to announce
+  # @return [void]
+  def transmit_session_changed(session)
+    transmit({
+      "action" => "session_changed",
+      "session_id" => session.id,
+      "message_count" => session.events.llm_messages.count,
+      "view_mode" => session.view_mode
+    })
+  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.
@@ -98,26 +195,123 @@ class SessionChannel < ApplicationCable::Channel
     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
+    transmit_session_changed(session)
+    transmit_history(session)
   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
+  # Transmits the current view_mode so the TUI initializes correctly.
+  # Sends `{action: "view_mode", view_mode: <mode>}` to the subscribing client.
+  #
+  # @param session [Session] the session whose view_mode to transmit
+  # @return [void]
+  def transmit_view_mode(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.
+  #
+  # @param session [Session] the session whose history to transmit
+  def transmit_history(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|
-      next unless event.llm_message?
+      ActionCable.server.broadcast(stream_name, decorate_event_payload(event, session.view_mode))
+    end
+  end
+
+  # Decorates an event for transmission to clients. Merges the event's
+  # database ID and structured decorator output into the payload.
+  # Used by {#transmit_history} and {#broadcast_viewport} for historical
+  # and viewport re-broadcast — live broadcasts use {Event::Broadcasting}.
+  #
+  # @param event [Event] persisted event record
+  # @param mode [String] view mode for decoration (default: "basic")
+  # @return [Hash] payload with "id" and optional "rendered" key
+  def decorate_event_payload(event, mode = "basic")
+    payload = event.payload.merge("id" => event.id)
+    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
 
-      transmit(event.payload)
+    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
+
+  # Merges the Anthropic subscription token into encrypted credentials,
+  # preserving existing keys (e.g. secret_key_base).
+  #
+  # @param token [String] validated Anthropic subscription token
+  # @return [void]
+  def write_anthropic_token(token)
+    creds = Rails.application.credentials
+    existing = begin
+      YAML.safe_load(creds.read) || {}
+    rescue ActiveSupport::EncryptedFile::MissingContentError
+      {}
     end
+    existing["anthropic"] ||= {}
+    existing["anthropic"]["subscription_token"] = token
+    creds.write(existing.to_yaml)
+    # Rails memoizes the decrypted config in @config. Without clearing it,
+    # subsequent credential reads return stale data. No public API exists
+    # for cache invalidation as of Rails 8.1.
+    creds.instance_variable_set(:@config, nil)
   end
 
   def transmit_error(message)

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

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