anima-core 1.2.0 → 1.3.0

data/lib/tools/response_truncator.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require "tempfile"
+
+module Tools
+  # Truncates oversized tool results to protect the agent's context window.
+  #
+  # When a tool returns more characters than the configured threshold,
+  # saves the full output to a temp file and returns a truncated version:
+  # first 10 lines + notice + last 10 lines. The agent can use the
+  # +read_file+ tool with offset/limit to inspect the full output.
+  #
+  # Two thresholds exist:
+  # - **Tool threshold** (~3000 chars) — for raw tool output (bash, web, etc.)
+  # - **Sub-agent threshold** (~24000 chars) — for curated sub-agent results
+  #
+  # @example Truncating a tool result
+  #   ResponseTruncator.truncate(huge_string, threshold: 3000)
+  #   # => "line 1\nline 2\n...\n---\n⚠️ Response truncated..."
+  module ResponseTruncator
+    HEAD_LINES = 10
+    TAIL_LINES = 10
+
+    # Attribution prefix for messages routed from sub-agent to parent.
+    # Shared by {Events::Subscribers::SubagentMessageRouter} and
+    # {Tools::MarkGoalCompleted} to keep formatting consistent.
+    ATTRIBUTION_FORMAT = "[sub-agent @%s]: %s"
+
+    NOTICE = <<~NOTICE.strip
+      ---
+      ⚠️ Response truncated (%<total>d lines total%<reason>s). Full output saved to: %<path>s
+      Use `read_file` tool with offset/limit to inspect specific sections.
+      ---
+    NOTICE
+
+    # Truncates content that exceeds the character threshold.
+    #
+    # @param content [Object] the tool result to (maybe) truncate; non-strings pass through unchanged
+    # @param threshold [Integer] character limit before truncation kicks in
+    # @param reason [String, nil] why truncation occurred (e.g. "bash output displays first/last 10 lines")
+    # @return [Object] original value if non-String/under threshold/few lines, truncated String otherwise
+    def self.truncate(content, threshold:, reason: nil)
+      return content unless content.is_a?(String)
+      return content if content.length <= threshold
+
+      lines = content.lines
+      total = lines.size
+      return content if total <= HEAD_LINES + TAIL_LINES
+
+      path = save_full_output(content)
+      head = lines.first(HEAD_LINES).join
+      tail = lines.last(TAIL_LINES).join
+      reason_text = reason ? " — #{reason}" : ""
+      notice = format(NOTICE, total: total, path: path, reason: reason_text)
+
+      "#{head}\n#{notice}\n\n#{tail}"
+    end
+
+    # Saves full content to a temp file that persists until system cleanup.
+    #
+    # @param content [String] the full tool result
+    # @return [String] absolute path to the saved file
+    def self.save_full_output(content)
+      file = Tempfile.create(["tool_result_", ".txt"])
+      file.write(content)
+      file.close
+      file.path
+    end
+  end
+end

data/lib/tools/spawn_specialist.rb

@@ -21,9 +21,9 @@ module Tools
 
     # Builds description dynamically to include available specialists.
     def self.description
-      base = "Spawn a specialist to work on a task. " \
-        "Its messages are forwarded to you. " \
-        "Address it via @name to send follow-up instructions."
+      base = "Need a specific skill set for the job? Bring in a specialist. " \
+        "Its messages appear in yours; any message containing " \
+        "@nickname is forwarded — even casual mentions will wake it."
 
       registry = Agents::Registry.instance
       return base unless registry.any?
@@ -85,7 +85,8 @@ module Tools
       nickname = child.name
       "Specialist @#{nickname} spawned (session #{child.id}). " \
         "Its messages will appear in your conversation. " \
-        "Reply with @#{nickname} to send it instructions."
+        "Reply with @#{nickname} to send it instructions — " \
+        "any message mentioning @#{nickname} is forwarded, even in narration."
     end
 
     private
@@ -96,7 +97,7 @@ module Tools
         prompt: build_prompt(definition),
         granted_tools: definition.tools
       )
-      child.create_user_message(task)
+      pin_goal_and_frame(child, task)
       assign_nickname_via_brain(child)
       child.broadcast_children_update_to_parent
       AgentRequestJob.perform_later(child.id)

data/lib/tools/spawn_subagent.rb

@@ -14,14 +14,15 @@ module Tools
   class SpawnSubagent < Base
     include SubagentPrompts
 
-    GENERIC_PROMPT = "You are a focused sub-agent. #{COMMUNICATION_INSTRUCTION}\n"
+    GENERIC_PROMPT = "#{COMMUNICATION_INSTRUCTION}\n"
 
     def self.tool_name = "spawn_subagent"
 
     def self.description
-      "Spawn a sub-agent to work on a task. " \
-        "It inherits your conversation context and its messages are forwarded to you. " \
-        "Address it via @nickname to send follow-up instructions."
+      "Task feels like a sidequest or a context-switch? Hand it off. " \
+        "Inherits your context; its messages appear in yours. " \
+        "Any message containing @nickname is forwarded — " \
+        "even casual mentions will wake the sub-agent."
     end
 
     def self.input_schema
@@ -67,7 +68,8 @@ module Tools
       nickname = child.name
       "Sub-agent @#{nickname} spawned (session #{child.id}). " \
         "Its messages will appear in your conversation. " \
-        "Reply with @#{nickname} to send it instructions."
+        "Reply with @#{nickname} to send it instructions — " \
+        "any message mentioning @#{nickname} is forwarded, even in narration."
     end
 
     private
@@ -78,7 +80,7 @@ module Tools
         prompt: GENERIC_PROMPT,
         granted_tools: granted_tools
       )
-      child.create_user_message(task)
+      pin_goal_and_frame(child, task)
       assign_nickname_via_brain(child)
       child.broadcast_children_update_to_parent
       AgentRequestJob.perform_later(child.id)

data/lib/tools/subagent_prompts.rb

@@ -1,23 +1,61 @@
 # frozen_string_literal: true
 
 module Tools
-  # Shared prompt fragments and nickname logic for tools that spawn sub-agent sessions.
+  # Shared prompt fragments and spawn logic for tools that create sub-agent sessions.
   # Included by {SpawnSubagent} and {SpawnSpecialist} to avoid duplication.
   module SubagentPrompts
-    COMMUNICATION_INSTRUCTION = "Your text messages are automatically forwarded to the parent agent. " \
-      "When you finish, write your final summary and stop — no special tool needed. " \
-      "If you need clarification, just ask — the parent can reply."
+    # Prepended to every sub-agent's stored prompt after nickname assignment.
+    # Establishes identity before any other instruction.
+    IDENTITY_TEMPLATE = "You are @%s, a sub-agent of the primary agent."
+
+    COMMUNICATION_INSTRUCTION = "Your messages reach the parent automatically. " \
+      "Ask if you need clarification — the parent can reply."
+
+    # Framing message inserted as the sub-agent's first user message.
+    # This is the "brake" between inherited parent context and the sub-agent's
+    # own task — without it, the model continues the parent's trajectory.
+    FORK_FRAMING_MESSAGE = "You were spawned to help with a single task. " \
+      "The messages above are the parent agent's context — background for your work, " \
+      "but the parent's goals are not yours. " \
+      "Your sole task is described in your Goal."
 
     private
 
-    # Runs the analytical brain synchronously to assign a nickname.
+    # Creates the sub-agent's Goal from the task description and inserts
+    # the framing message as the first user message.
+    #
+    # @param child [Session] the newly created child session
+    # @param task [String] the task description to pin as the sole Goal
+    # @return [void]
+    def pin_goal_and_frame(child, task)
+      child.goals.create!(description: task)
+      child.create_user_message(FORK_FRAMING_MESSAGE)
+    end
+
+    # Runs the analytical brain synchronously to assign a nickname,
+    # then prepends identity context to the stored prompt.
     # Falls back to a sequential "agent-N" name on any failure.
+    # Identity injection runs in +ensure+ so it applies to both
+    # brain-assigned and fallback nicknames.
     def assign_nickname_via_brain(child)
       AnalyticalBrain::Runner.new(child).call
       child.reload
     rescue => error
       Rails.logger.warn("Sub-agent nickname assignment failed: #{error.message}")
       child.update!(name: fallback_nickname)
+    ensure
+      inject_identity_context(child)
+    end
+
+    # Prepends identity context (nickname + sub-agent status) to the child's
+    # stored prompt. Called after nickname assignment so the sub-agent knows
+    # who it is from first token.
+    #
+    # @param child [Session] the child session with a nickname already set
+    # @return [void]
+    def inject_identity_context(child)
+      identity = format(IDENTITY_TEMPLATE, child.name)
+      child.update!(prompt: "#{identity}\n#{child.prompt}")
     end
 
     def fallback_nickname

data/lib/tools/think.rb

@@ -13,6 +13,10 @@ module Tools
   # - **inner** (default) — silent reasoning, visible only in verbose/debug
   # - **aloud** — narration shown in all view modes with a thought bubble
   #
+  # The +maxLength+ on thoughts is controlled by +thinking_budget+ in settings.
+  # Sub-agents receive half the main agent's budget — their tasks are scoped
+  # and less complex, so runaway reasoning is a stronger signal of confusion.
+  #
   # @example Silent planning between tool calls
   #   think(thoughts: "Three auth failures — likely a config issue, not individual tests.")
   #
@@ -23,6 +27,8 @@ module Tools
 
     def self.description = "Think out loud or silently."
 
+    # Schema is static — maxLength is injected at runtime by the registry
+    # via {#dynamic_schema} when session context is available.
     def self.input_schema
       {
         type: "object",
@@ -38,6 +44,23 @@ module Tools
       }
     end
 
+    # @param session [Session, nil] current session for budget calculation
+    def initialize(session: nil, **)
+      @session = session
+    end
+
+    # Returns the tool schema with a thinking budget applied as maxLength
+    # on the thoughts property. Sub-agents get half the budget.
+    #
+    # @return [Hash] Anthropic tool schema with maxLength constraint
+    def dynamic_schema
+      schema = self.class.schema.deep_dup
+      budget = Anima::Settings.thinking_budget
+      budget /= 2 if @session&.sub_agent?
+      schema[:input_schema][:properties][:thoughts][:maxLength] = budget
+      schema
+    end
+
     # @param input [Hash] with "thoughts" and optional "visibility"
     # @return [String] acknowledgement — the value is in the call, not the result
     def execute(input)

data/lib/tools/write.rb

@@ -15,7 +15,7 @@ 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 = "Write file."
 

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.
     #