anima-core 1.1.3 → 1.3.0

data/lib/tools/write.rb

@@ -15,16 +15,16 @@ module Tools
   #   tool.execute("path" => "README.md", "content" => "# Title\n")
   #   # => "Wrote 9 bytes to /home/user/project/README.md"
   class Write < Base
-    def self.tool_name = "write"
+    def self.tool_name = "write_file"
 
-    def self.description = "Create or overwrite a file. Creates intermediate directories automatically. Use for new files or full replacement."
+    def self.description = "Write file."
 
     def self.input_schema
       {
         type: "object",
         properties: {
-          path: {type: "string", description: "Absolute or relative file path (relative resolved against working directory)"},
-          content: {type: "string", description: "Full file content to write"}
+          path: {type: "string", description: "Relative paths resolve against working directory. Creates intermediate directories."},
+          content: {type: "string"}
         },
         required: %w[path content]
       }

data/lib/tui/app.rb

@@ -21,7 +21,7 @@ module TUI
     }.freeze
 
     MENU_LABELS = (COMMAND_KEYS.map { |key, action| "[#{key}] #{action.to_s.tr("_", " ").capitalize}" } +
-      ["[\u2191] Scroll chat", "[\u2193] Return to input"]).freeze
+      ["[\u2191] Scroll chat", "[\u2193] Return to input", "[\u2192] Scroll HUD"]).freeze
 
     # HUD occupies 1/3 of screen width, clamped to a usable minimum.
     HUD_MIN_WIDTH = 24
@@ -78,10 +78,16 @@ module TUI
     # Grace period for watchdog thread to exit before force-killing it.
     WATCHDOG_SHUTDOWN_TIMEOUT = 1
 
+    # HUD scroll step sizes (lines per event).
+    HUD_SCROLL_STEP = 1
+    HUD_MOUSE_SCROLL_STEP = 2
+
     attr_reader :current_screen, :command_mode, :session_picker_active,
       :view_mode_picker_active
     # @return [Boolean] true when the HUD info panel is visible
     attr_reader :hud_visible
+    # @return [Boolean] true when the HUD pane has keyboard focus for scrolling
+    attr_reader :hud_focused
     # @return [Boolean] true when the token setup popup overlay is visible
     attr_reader :token_setup_active
     # @return [Boolean] true when graceful shutdown has been requested via signal
@@ -102,6 +108,11 @@ module TUI
       @session_picker_mode = :root
       @session_picker_parent_id = nil
       @hud_visible = true
+      @hud_focused = false
+      @hud_scroll_offset = 0
+      @hud_max_scroll = 0
+      @hud_visible_height = 0
+      @hud_content_area = nil
       @view_mode_picker_active = false
       @view_mode_picker_index = 0
       @token_setup_active = false
@@ -197,8 +208,13 @@ module TUI
     GOAL_ICON_ACTIVE = "\u25CF"       # ●
     GOAL_ICON_IN_PROGRESS = "\u25D0"  # ◐
     GOAL_ICON_COMPLETED = "\u2713"    # ✓
-    CHILD_ICON_RUNNING = "\u25CF"     # ●
-    CHILD_ICON_IDLE = "\u25CC"        # ◌
+
+    # Sub-agent state icons — form communicates type of work,
+    # color communicates status. Work independently.
+    CHILD_ICON_IDLE = "\u25CC"              # ◌ hollow — nothing happening
+    CHILD_ICON_GENERATING = "\u25CF"        # ● filled — LLM thinking
+    CHILD_ICON_TOOL_EXECUTING = "\u25C9"    # ◉ dot-in-circle — tool running
+    CHILD_ICON_INTERRUPTING = "\u25CF"      # ● filled — stopping
 
     def render_info(frame, area, tui)
       session = @screens[:chat].session_info
@@ -218,8 +234,10 @@ module TUI
     end
 
     # Renders the main HUD content: session name, goals, skills,
-    # workflow, and sub-agents.
+    # workflow, and sub-agents. Supports vertical scrolling with
+    # a scrollbar when content exceeds the visible area.
     def render_hud_content(frame, area, tui, session)
+      @hud_content_area = area
       session_label = session[:name] || "##{session[:id]}"
 
       lines = [
@@ -234,16 +252,42 @@ module TUI
         interaction_state_line(tui)
       ].flatten.compact
 
+      @hud_visible_height = [area.height - 2, 0].max
+      inner_width = [area.width - 2, 1].max
+      total_height = tui.paragraph(text: lines, wrap: true).line_count(inner_width)
+      @hud_max_scroll = [total_height - @hud_visible_height, 0].max
+      @hud_scroll_offset = @hud_scroll_offset.clamp(0, @hud_max_scroll)
+
+      border_color = @hud_focused ? "yellow" : "white"
+
       content = tui.paragraph(
         text: lines,
         wrap: true,
+        scroll: [@hud_scroll_offset, 0],
         block: tui.block(
           borders: [:left, :top, :right],
           border_type: :rounded,
-          border_style: {fg: "white"}
+          border_style: {fg: border_color}
         )
       )
       frame.render_widget(content, area)
+
+      render_hud_scrollbar(frame, area, tui)
+    end
+
+    # Renders a scrollbar on the right edge of the HUD when content overflows.
+    def render_hud_scrollbar(frame, area, tui)
+      return unless @hud_max_scroll > 0
+
+      scrollbar = tui.scrollbar(
+        content_length: @hud_max_scroll,
+        position: @hud_scroll_offset,
+        orientation: :vertical_right,
+        thumb_style: {fg: "cyan"},
+        track_symbol: "\u2502",
+        track_style: {fg: "dark_gray"}
+      )
+      frame.render_widget(scrollbar, area)
     end
 
     # Renders the bottom status bar: connection state and model name.
@@ -382,26 +426,44 @@ module TUI
     end
 
     # Returns the activity icon and color for a child session.
+    # Form communicates type of work, color communicates status —
+    # they work independently so even without color the shape tells
+    # the story.
     #
-    # @param child [Hash] child session data with "processing" key
+    # @param child [Hash] child session data with "session_state" key
     # @return [Array(String, String)] icon and color pair
     def child_icon_and_color(child)
-      if child["processing"]
-        [CHILD_ICON_RUNNING, "yellow"]
+      case child["session_state"]
+      when "llm_generating"
+        [CHILD_ICON_GENERATING, "green"]
+      when "tool_executing"
+        [CHILD_ICON_TOOL_EXECUTING, "green"]
+      when "interrupting"
+        [CHILD_ICON_INTERRUPTING, "red"]
       else
-        [CHILD_ICON_IDLE, "green"]
+        [CHILD_ICON_IDLE, "dark_gray"]
       end
     end
 
-    # Shows "Scrolling" when chat pane is focused, "Thinking..." during LLM processing.
+    # Shows focus mode when a pane is focused, or the braille spinner
+    # during active processing.
     def interaction_state_line(tui)
-      if @screens[:chat].chat_focused
+      if @hud_focused
+        tui.line(spans: [
+          tui.span(content: "HUD Scroll", style: tui.style(fg: "yellow", modifiers: [:bold]))
+        ])
+      elsif @screens[:chat].chat_focused
         tui.line(spans: [
           tui.span(content: "Scrolling", style: tui.style(fg: "yellow", modifiers: [:bold]))
         ])
       elsif chat_loading?
+        chat = @screens[:chat]
+        char = chat.spinner.tick || "\u2800"
+        color = chat.spinner_color
+        label = chat.spinner_label
         tui.line(spans: [
-          tui.span(content: "Thinking...", style: tui.style(fg: "magenta", modifiers: [:bold]))
+          tui.span(content: "#{char} ", style: tui.style(fg: color, modifiers: [:bold])),
+          tui.span(content: label, style: tui.style(fg: color))
         ])
       end
     end
@@ -410,6 +472,38 @@ module TUI
       @screens[:chat].loading?
     end
 
+    # Switches keyboard focus to the HUD pane for scrolling.
+    # Unfocuses the chat pane if it was focused.
+    #
+    # @return [void]
+    def focus_hud
+      @screens[:chat].unfocus_chat if @screens[:chat].chat_focused
+      @hud_focused = true
+    end
+
+    # Returns keyboard focus from the HUD pane.
+    #
+    # @return [void]
+    def unfocus_hud
+      @hud_focused = false
+    end
+
+    # Scrolls the HUD viewport up, clamping at the top.
+    #
+    # @param lines [Integer] number of lines to scroll
+    # @return [void]
+    def scroll_hud_up(lines)
+      @hud_scroll_offset = [@hud_scroll_offset - lines, 0].max
+    end
+
+    # Scrolls the HUD viewport down, clamping at max_scroll.
+    #
+    # @param lines [Integer] number of lines to scroll
+    # @return [void]
+    def scroll_hud_down(lines)
+      @hud_scroll_offset = [@hud_scroll_offset + lines, @hud_max_scroll].min
+    end
+
     def handle_event(event)
       return nil if event.none?
       return :quit if event.ctrl_c?
@@ -422,6 +516,8 @@ module TUI
         handle_view_mode_picker(event)
       elsif @command_mode
         handle_command_mode(event)
+      elsif @hud_focused
+        handle_hud_focused_event(event)
       else
         handle_normal_mode(event)
       end
@@ -442,6 +538,11 @@ module TUI
         return nil
       end
 
+      if event.right? && @hud_visible
+        focus_hud
+        return nil
+      end
+
       action = COMMAND_KEYS[event.code]
       case action
       when :quit
@@ -451,6 +552,7 @@ module TUI
         nil
       when :toggle_hud
         @hud_visible = !@hud_visible
+        unfocus_hud if !@hud_visible
         nil
       when :new_session
         @screens[:chat].new_session
@@ -466,7 +568,13 @@ module TUI
     end
 
     def handle_normal_mode(event)
-      if event.mouse? || event.paste?
+      if event.paste?
+        delegate_to_screen(event)
+        return nil
+      end
+
+      if event.mouse?
+        return nil if route_mouse_to_hud(event)
         delegate_to_screen(event)
         return nil
       end
@@ -497,6 +605,63 @@ module TUI
       nil
     end
 
+    # Handles keyboard events when the HUD pane has focus.
+    # Arrow keys and Page Up/Down scroll the HUD; Escape and Ctrl+A exit.
+    def handle_hud_focused_event(event)
+      return nil if event.none?
+      return :quit if event.ctrl_c?
+
+      if event.mouse?
+        return nil if route_mouse_to_hud(event)
+        delegate_to_screen(event)
+        return nil
+      end
+
+      return nil unless event.key?
+
+      if event.esc? || ctrl_a?(event)
+        unfocus_hud
+        return nil
+      end
+
+      if event.up?
+        scroll_hud_up(HUD_SCROLL_STEP)
+      elsif event.down?
+        scroll_hud_down(HUD_SCROLL_STEP)
+      elsif event.page_up?
+        scroll_hud_up(@hud_visible_height)
+      elsif event.page_down?
+        scroll_hud_down(@hud_visible_height)
+      elsif event.home?
+        scroll_hud_up(@hud_max_scroll)
+      elsif event.end?
+        scroll_hud_down(@hud_max_scroll)
+      end
+      nil
+    end
+
+    # Routes mouse scroll events to the HUD when the cursor is over the HUD area.
+    # @return [Boolean] true if the event was handled by the HUD
+    def route_mouse_to_hud(event)
+      return false if !@hud_visible || !@hud_content_area
+      return false unless mouse_over_hud?(event)
+      return false unless event.scroll_up? || event.scroll_down?
+
+      if event.scroll_up?
+        scroll_hud_up(HUD_MOUSE_SCROLL_STEP)
+      else
+        scroll_hud_down(HUD_MOUSE_SCROLL_STEP)
+      end
+      true
+    end
+
+    # Checks whether a mouse event's coordinates fall within the HUD content area.
+    def mouse_over_hud?(event)
+      area = @hud_content_area
+      event.x >= area.x && event.x < area.x + area.width &&
+        event.y >= area.y && event.y < area.y + area.height
+    end
+
     # Switches to the parent session when viewing a child (sub-agent) session.
     # No-op if the current session is a root session.
     #

data/lib/tui/braille_spinner.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module TUI
+  # Animated braille spinner that communicates session state through distinct
+  # visual patterns. Each state gets its own animation — a user watching long
+  # enough starts _feeling_ the difference between LLM thinking and tool
+  # execution without reading text.
+  #
+  # The 2x4 braille grid (U+2800-U+28FF) encodes 8 dots in a single character
+  # cell. Dot positions map to bit flags:
+  #
+  #   ┌───┬───┐
+  #   │ 0 │ 3 │   bit 0 = top-left,     bit 3 = top-right
+  #   │ 1 │ 4 │   bit 1 = mid-left,     bit 4 = mid-right
+  #   │ 2 │ 5 │   bit 2 = lower-left,   bit 5 = lower-right
+  #   │ 6 │ 7 │   bit 6 = bottom-left,  bit 7 = bottom-right
+  #   └───┴───┘
+  #
+  # During LLM generation, a snake weaves through the grid — organic,
+  # unpredictable movement like watching a campfire. During tool execution,
+  # a fast staccato pulse signals mechanical work. Interrupting decelerates
+  # to a freeze.
+  #
+  # @example Basic usage
+  #   spinner = BrailleSpinner.new
+  #   spinner.state = "llm_generating"
+  #   char = spinner.tick  # => "⠋" (braille pattern)
+  class BrailleSpinner
+    # Clockwise traversal of the 8 dots in the braille grid.
+    # Produces a smooth rotating animation — one dot lit at a time.
+    SNAKE_FRAMES = [
+      0x01, # ⠁ dot 0 (top-left)
+      0x02, # ⠂ dot 1 (mid-left)
+      0x04, # ⠄ dot 2 (lower-left)
+      0x40, # ⡀ dot 6 (bottom-left)
+      0x80, # ⢀ dot 7 (bottom-right)
+      0x20, # ⠠ dot 5 (lower-right)
+      0x10, # ⠐ dot 4 (mid-right)
+      0x08  # ⠈ dot 3 (top-right)
+    ].freeze
+
+    # Snake animation: 3 consecutive dots form a growing/moving tail.
+    # Each frame is the OR of 3 adjacent positions in SNAKE_FRAMES,
+    # creating a worm-like creature circling the grid.
+    SNAKE_TRAIL_FRAMES = SNAKE_FRAMES.each_index.map { |idx|
+      SNAKE_FRAMES[idx] | SNAKE_FRAMES[(idx + 1) % 8] | SNAKE_FRAMES[(idx + 2) % 8]
+    }.freeze
+
+    # Tool execution: alternating dot patterns for a staccato pulse.
+    # Fast, mechanical, clearly different from the smooth snake.
+    TOOL_FRAMES = [
+      0x09, # ⠉ dots 0+3 (top row)
+      0x12, # ⠒ dots 1+4 (middle row)
+      0x24, # ⠤ dots 2+5 (lower row)
+      0xC0, # ⣀ dots 6+7 (bottom row)
+      0x24, # ⠤ dots 2+5 (lower row)
+      0x12  # ⠒ dots 1+4 (middle row)
+    ].freeze
+
+    # Interrupting: rapid deceleration — full grid fading to empty.
+    INTERRUPT_FRAMES = [
+      0xFF, # ⣿ all dots
+      0xDB, # ⣛ most dots
+      0x49, # ⡉ sparse
+      0x00, # ⠀ empty
+      0x49, # ⡉ sparse
+      0xFF  # ⣿ all dots
+    ].freeze
+
+    # Braille Unicode block base codepoint.
+    BRAILLE_BASE = 0x2800
+
+    # Ticks per frame for each state — controls animation speed.
+    # Higher = slower. At ~15fps render loop: 2 = ~7.5fps, 4 = ~3.75fps.
+    SPEED = {
+      "llm_generating" => 2,
+      "tool_executing" => 1,
+      "interrupting" => 1
+    }.freeze
+
+    # @return [String] current session state
+    attr_reader :state
+
+    def initialize
+      @state = "idle"
+      @frame_index = 0
+      @tick_count = 0
+    end
+
+    # Updates the session state driving the animation.
+    # Resets frame position on state change for a clean transition.
+    #
+    # @param new_state [String] one of "idle", "llm_generating",
+    #   "tool_executing", "interrupting"
+    def state=(new_state)
+      if @state != new_state
+        @frame_index = 0
+        @tick_count = 0
+      end
+      @state = new_state
+    end
+
+    # Advances the animation by one tick and returns the current
+    # braille character. Returns nil when idle (no animation).
+    #
+    # @return [String, nil] single braille character, or nil when idle
+    def tick
+      return nil if @state == "idle"
+
+      frames = frames_for_state
+      return nil unless frames
+
+      speed = SPEED.fetch(@state, 2)
+      @tick_count += 1
+      if @tick_count >= speed
+        @tick_count = 0
+        @frame_index = (@frame_index + 1) % frames.size
+      end
+
+      (BRAILLE_BASE + frames[@frame_index]).chr(Encoding::UTF_8)
+    end
+
+    # Returns the current frame character without advancing.
+    #
+    # @return [String, nil] single braille character, or nil when idle
+    def current
+      return nil if @state == "idle"
+
+      frames = frames_for_state
+      return nil unless frames
+
+      (BRAILLE_BASE + frames[@frame_index]).chr(Encoding::UTF_8)
+    end
+
+    # Whether the spinner is actively animating.
+    #
+    # @return [Boolean]
+    def active?
+      @state != "idle"
+    end
+
+    private
+
+    def frames_for_state
+      case @state
+      when "llm_generating" then SNAKE_TRAIL_FRAMES
+      when "tool_executing" then TOOL_FRAMES
+      when "interrupting" then INTERRUPT_FRAMES
+      end
+    end
+  end
+end

data/lib/tui/cable_client.rb

@@ -129,9 +129,9 @@ module TUI
     # Requests the brain to recall (delete) a pending message so the user
     # can edit it before the LLM sees it.
     #
-    # @param event_id [Integer] database ID of the pending user_message event
-    def recall_pending(event_id)
-      send_action("recall_pending", {"event_id" => event_id})
+    # @param pending_message_id [Integer] database ID of the {PendingMessage}
+    def recall_pending(pending_message_id)
+      send_action("recall_pending", {"pending_message_id" => pending_message_id})
     end
 
     # Requests interruption of the current tool execution. The server sets
@@ -143,7 +143,7 @@ module TUI
     end
 
     # Sends an Anthropic subscription token to the brain for validation and storage.
-    # The token flows directly from TUI input to encrypted credentials — never
+    # The token flows directly from TUI input to the encrypted secrets table — never
     # enters the LLM context window.
     #
     # @param token [String] Anthropic subscription token (sk-ant-oat01-...)

data/lib/tui/decorators/base_decorator.rb

@@ -71,6 +71,8 @@ module TUI
       end
 
       # Generic tool response rendering — success/failure indicator and content.
+      # Token counts get their own color-coded span so expensive responses
+      # visually jump out in debug mode.
       # Subclasses override for tool-specific presentation.
       #
       # @param tui [RatatuiRuby] TUI rendering API
@@ -79,16 +81,22 @@ module TUI
         indicator = (data["success"] == false) ? ERROR_ICON : CHECKMARK
         tool_id = data["tool_use_id"]
         tokens = data["tokens"]
+        style = tui.style(fg: response_color)
 
         meta_parts = []
         meta_parts << "[#{tool_id}]" if tool_id
         meta_parts << indicator
-        meta_parts << format_token_label(tokens, data["estimated"]) if tokens
         prefix = "  #{RETURN_ARROW} #{meta_parts.join(" ")} "
 
         content_lines = data["content"].to_s.split("\n", -1)
-        style = tui.style(fg: response_color)
-        lines = [tui.line(spans: [tui.span(content: "#{prefix}#{content_lines.first}", style: style)])]
+        first_line_spans = [tui.span(content: prefix, style: style)]
+        if tokens
+          tok_label = format_token_label(tokens, data["estimated"])
+          first_line_spans << tui.span(content: "#{tok_label} ", style: tui.style(fg: token_count_color(tokens)))
+        end
+        first_line_spans << tui.span(content: content_lines.first.to_s, style: style)
+
+        lines = [tui.line(spans: first_line_spans)]
         content_lines.drop(1).each { |line| lines << tui.line(spans: [tui.span(content: "    #{line}", style: style)]) }
         lines
       end
@@ -108,10 +116,11 @@ module TUI
         ICON
       end
 
-      # Color for tool call headers. Subclasses override for tool-specific colors.
+      # Unified color for all tool call headers. Keeps tool invocations
+      # visually distinct from conversation messages (user/assistant/thought).
       # @return [String]
       def color
-        "white"
+        "magenta"
       end
 
       # Color for tool response content. Subclasses override for tool-specific colors.
@@ -152,9 +161,9 @@ module TUI
         case tool_name
         when "bash" then BashDecorator
         when "think" then ThinkDecorator
-        when "read" then ReadDecorator
-        when "edit" then EditDecorator
-        when "write" then WriteDecorator
+        when "read_file" then ReadDecorator
+        when "edit_file" then EditDecorator
+        when "write_file" then WriteDecorator
         when "web_get" then WebGetDecorator
         else self
         end

data/lib/tui/decorators/bash_decorator.rb

@@ -3,8 +3,8 @@
 module TUI
   module Decorators
     # Renders bash tool calls and responses.
-    # Calls show the shell command with a terminal icon.
-    # Responses use green for success, red for failure.
+    # Calls show the shell command with a terminal icon in the unified tool color.
+    # Responses use green for success, red for failure — immediate actionable feedback.
     class BashDecorator < BaseDecorator
       ICON = "\u{1F4BB}" # laptop / terminal
 

data/lib/tui/decorators/edit_decorator.rb

@@ -2,8 +2,9 @@
 
 module TUI
   module Decorators
-    # Renders edit tool calls and responses.
-    # Calls show the file path with a pencil icon.
+    # Renders edit_file tool calls and responses.
+    # Calls show the file path with a pencil icon in the unified tool color.
+    # Responses use the CRUD Update color (light_yellow) to flag modifications.
     class EditDecorator < BaseDecorator
       ICON = "\u270F\uFE0F" # pencil
 
@@ -11,8 +12,8 @@ module TUI
         ICON
       end
 
-      def color
-        "yellow"
+      def response_color
+        "light_yellow"
       end
     end
   end

data/lib/tui/decorators/read_decorator.rb

@@ -2,9 +2,9 @@
 
 module TUI
   module Decorators
-    # Renders read tool calls and responses.
-    # Calls show the file path with a page icon.
-    # Responses show file content in dim text.
+    # Renders read_file tool calls and responses.
+    # Calls show the file path with a page icon in the unified tool color.
+    # Responses use the CRUD Read color (light_blue) for informational content.
     class ReadDecorator < BaseDecorator
       ICON = "\u{1F4C4}" # page facing up
 
@@ -12,12 +12,8 @@ module TUI
         ICON
       end
 
-      def color
-        "cyan"
-      end
-
       def response_color
-        "dark_gray"
+        "light_blue"
       end
     end
   end

data/lib/tui/decorators/think_decorator.rb

@@ -3,8 +3,8 @@
 module TUI
   module Decorators
     # Renders think tool events — the agent's inner reasoning.
-    # "aloud" thoughts use yellow (narration for the user), "inner"
-    # thoughts use dark_gray (dimmed to signal internality).
+    # Both "aloud" and "inner" thoughts use grey (dark_gray) to visually
+    # de-emphasize reasoning content vs. actual conversation output.
     class ThinkDecorator < BaseDecorator
       THOUGHT_BUBBLE = "\u{1F4AD}" # thought balloon
 
@@ -17,9 +17,7 @@ module TUI
       # @param tui [RatatuiRuby] TUI rendering API
       # @return [Array<RatatuiRuby::Widgets::Line>]
       def render_think(tui)
-        aloud = data["visibility"] == "aloud"
-        fg = aloud ? "yellow" : "dark_gray"
-        style = tui.style(fg: fg)
+        style = tui.style(fg: "dark_gray")
         ts = data["timestamp"]
 
         meta = []

data/lib/tui/decorators/web_get_decorator.rb

@@ -3,7 +3,8 @@
 module TUI
   module Decorators
     # Renders web_get tool calls and responses.
-    # Calls show the URL with a globe icon.
+    # Calls show the URL with a globe icon in the unified tool color.
+    # Responses use the CRUD Read color (light_blue) for fetched content.
     class WebGetDecorator < BaseDecorator
       ICON = "\u{1F310}" # globe with meridians
 
@@ -11,8 +12,8 @@ module TUI
         ICON
       end
 
-      def color
-        "blue"
+      def response_color
+        "light_blue"
       end
     end
   end