anima-core 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fcb9e1d40357cd0eabdc5fffa01f8727b449a5b85e6f7b7dbe9033fae461bec9
-  data.tar.gz: d785a36f13e3a3e698b80dd123544ca6dbee535372b92776a5b7993e4125baa1
+  metadata.gz: 9517757f2c4fdb8b19d204a154d3badd3c3b8fb456dffaf03236b2d7c065378d
+  data.tar.gz: a0d26e0b27fd1d2df0c46c3a4bbad822ac3517d1d02b41a6bdd49195de64e71f
 SHA512:
-  metadata.gz: d84d91dc67fe56617f294b9a6982e830ac36c242fdb203bfa601c2e6fb009dd8a3d9d5243c4bfa501d7069e40bb08d15d920717374a79825ff1af7b4812713de
-  data.tar.gz: d61f7ed56737c02f4412bcdee5d15e9b4b8e3b63f45011aa9e8ae2c1a80725413841ad1ed95d7f02ab6a8e532e0a36f0fd9abc39b50adb5fed0dbb21ec599604
+  metadata.gz: d150e5f97a3a2055c66cfaa773c7bd1dd33354b869fe38d6fa25b2b47352c76cec0c222f44aa4eb7e7e65b61098b7531e61522a01e6dd1d722ee9224c7759aea
+  data.tar.gz: 0f9ef56323a4598ed8dc3dca79e6ec9cf1e63ea9dff8751612cd32691aa0968e629144b4f7c47150cd9c9861f3d74e323c852433e1aa066732bb10fc8db235fc

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 ## [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

data/README.md

@@ -194,7 +194,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 +343,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

@@ -15,13 +15,14 @@ class SessionChannel < ApplicationCable::Channel
 
   # 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.
+  # 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
@@ -85,6 +86,23 @@ class SessionChannel < ApplicationCable::Channel
     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
@@ -102,24 +120,98 @@ class SessionChannel < ApplicationCable::Channel
     transmit({
       "action" => "session_changed",
       "session_id" => new_id,
-      "message_count" => session.events.llm_messages.count
+      "message_count" => session.events.llm_messages.count,
+      "view_mode" => session.view_mode
     })
     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.
+  # 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|
-      next unless event.llm_message?
+      transmit(decorate_event_payload(event, session.view_mode))
+    end
+  end
 
-      transmit(event.payload)
+  # 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

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

data/app/decorators/tool_call_decorator.rb

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

data/app/decorators/tool_response_decorator.rb

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

data/app/decorators/user_message_decorator.rb

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

data/app/models/event.rb

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

data/app/models/session.rb

@@ -7,13 +7,22 @@ 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.
@@ -35,6 +44,15 @@ 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
@@ -97,18 +115,12 @@ class Session < ApplicationRecord
     }
   end
 
-  # Rough estimate for events not yet counted by the background job.
-  # For tool events, estimates from the full payload since tool_input
-  # and tool metadata contribute to token count.
+  # Delegates to {Event#estimate_tokens} for events not yet counted
+  # by the background job.
   #
   # @param event [Event]
   # @return [Integer] at least 1
   def estimate_tokens(event)
-    text = if event.event_type.in?(%w[tool_call tool_response])
-      event.payload.to_json
-    else
-      event.payload["content"].to_s
-    end
-    [(text.bytesize / BYTES_PER_TOKEN.to_f).ceil, 1].max
+    event.estimate_tokens
   end
 end

data/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"