anima-core 0.3.0 → 1.0.0

data/lib/tui/screens/chat.rb

@@ -28,7 +28,8 @@ module TUI
       VIEW_MODES = %w[basic verbose debug].freeze
 
       attr_reader :message_store, :scroll_offset, :session_info, :view_mode, :sessions_list,
-        :authentication_required, :token_save_result
+        :authentication_required, :token_save_result, :parent_session_id,
+        :chat_focused
 
       # @param cable_client [TUI::CableClient] WebSocket client connected to the brain
       # @param message_store [TUI::MessageStore, nil] injectable for testing
@@ -43,10 +44,15 @@ module TUI
         @max_scroll = 0
         @input_scroll_offset = 0
         @view_mode = "basic"
-        @session_info = {id: cable_client.session_id || 0, message_count: 0}
+        @session_info = {id: cable_client.session_id || 0, message_count: 0, active_skills: [], active_workflow: nil, goals: []}
         @sessions_list = nil
+        @parent_session_id = nil
         @authentication_required = false
         @token_save_result = nil
+        @chat_focused = false
+        @input_history = []
+        @history_index = nil
+        @saved_input = nil
       end
 
       def messages
@@ -81,28 +87,40 @@ module TUI
         render_input(frame, input_area, tui)
       end
 
-      # Input is always active — users can type and send messages even while
-      # the agent is processing. Messages sent during processing are queued
-      # as "pending" on the server and delivered after the current loop.
-      # Arrow-up recalls the last pending message for editing.
+      # Dispatches keyboard, mouse, and paste events. Supports two focus
+      # modes: input mode (default) where arrows navigate the input buffer
+      # with bash-style history overflow, and chat-focused mode where arrows
+      # scroll the chat pane.
+      #
+      # Page Up/Down and mouse scroll always control the chat pane
+      # regardless of focus mode.
       def handle_event(event)
         return handle_mouse_event(event) if event.mouse?
         return handle_paste_event(event) if event.paste?
         return handle_scroll_key(event) if event.page_up? || event.page_down?
 
+        return handle_chat_focused_event(event) if @chat_focused
+
         if event.up?
+          return true if @input_buffer.move_up
           return true if @input_buffer.text.empty? && recall_pending_message
-          return handle_scroll_key(event)
+          return navigate_history_back
+        end
+
+        if event.down?
+          return true if @input_buffer.move_down
+          return navigate_history_forward
         end
-        return handle_scroll_key(event) if event.down?
 
         if event.enter?
           submit_message
           true
         elsif event.backspace?
+          reset_history_browsing
           @input_buffer.backspace
           true
         elsif event.delete?
+          reset_history_browsing
           @input_buffer.delete
           true
         elsif event.left?
@@ -114,6 +132,7 @@ module TUI
         elsif event.end?
           @input_buffer.move_end
         elsif printable_char?(event) && !@input_buffer.full?
+          reset_history_browsing
           @input_buffer.insert(event.code)
         else
           false
@@ -167,6 +186,18 @@ module TUI
         @loading
       end
 
+      # Switches focus to the chat pane for keyboard scrolling.
+      # @return [void]
+      def focus_chat
+        @chat_focused = true
+      end
+
+      # Returns focus from the chat pane to the input field.
+      # @return [void]
+      def unfocus_chat
+        @chat_focused = false
+      end
+
       private
 
       # Drains the WebSocket message queue and feeds events to the message store
@@ -182,6 +213,14 @@ module TUI
             handle_view_mode_changed(msg)
           when "view_mode"
             @view_mode = msg["view_mode"] if msg["view_mode"]
+          when "session_name_updated"
+            handle_session_name_updated(msg)
+          when "active_skills_updated"
+            handle_active_skills_updated(msg)
+          when "active_workflow_updated"
+            handle_active_workflow_updated(msg)
+          when "goals_updated"
+            handle_goals_updated(msg)
           when "sessions_list"
             @sessions_list = msg["sessions"]
           when "user_message_recalled"
@@ -215,9 +254,23 @@ module TUI
               @message_store.process_event(msg)
             end
           end
+
+          handle_viewport_evictions(msg)
         end
       end
 
+      # Removes messages that left the LLM's context window. Event broadcasts
+      # include `evicted_event_ids` when old events are pushed out of the
+      # viewport by new ones.
+      #
+      # @param msg [Hash] incoming WebSocket message
+      def handle_viewport_evictions(msg)
+        evicted_ids = msg["evicted_event_ids"]
+        return unless evicted_ids.is_a?(Array) && evicted_ids.any?
+
+        @message_store.remove_by_ids(evicted_ids)
+      end
+
       # Reacts to connection lifecycle changes from the WebSocket client.
       # Clears stale state when subscription begins so the store is empty
       # before history arrives. Action Cable sends confirm_subscription
@@ -239,12 +292,49 @@ module TUI
         @cable_client.update_session_id(new_id)
         @message_store.clear
         @view_mode = msg["view_mode"] if msg["view_mode"]
-        @session_info = {id: new_id, message_count: msg["message_count"] || 0}
+        @session_info = {id: new_id, name: msg["name"], message_count: msg["message_count"] || 0,
+                         active_skills: msg["active_skills"] || [], active_workflow: msg["active_workflow"],
+                         goals: msg["goals"] || []}
+        @parent_session_id = msg["parent_session_id"]
         @input_buffer.clear
         @loading = false
         @scroll_offset = 0
         @auto_scroll = true
         @input_scroll_offset = 0
+        @chat_focused = false
+        reset_history_browsing
+      end
+
+      # Updates the session name when a background job generates one.
+      # Only applies to the current session.
+      def handle_session_name_updated(msg)
+        return unless msg["session_id"] == @session_info[:id]
+
+        @session_info[:name] = msg["name"]
+      end
+
+      # Updates the active skills list when the analytical brain activates or
+      # deactivates skills. Only applies to the current session.
+      def handle_active_skills_updated(msg)
+        return unless msg["session_id"] == @session_info[:id]
+
+        @session_info[:active_skills] = msg["active_skills"] || []
+      end
+
+      # Updates the active workflow when the analytical brain activates or
+      # deactivates a workflow. Only applies to the current session.
+      def handle_active_workflow_updated(msg)
+        return unless msg["session_id"] == @session_info[:id]
+
+        @session_info[:active_workflow] = msg["active_workflow"]
+      end
+
+      # Updates the goals list when the analytical brain creates or
+      # completes goals. Only applies to the current session.
+      def handle_goals_updated(msg)
+        return unless msg["session_id"] == @session_info[:id]
+
+        @session_info[:goals] = msg["goals"] || []
       end
 
       # Handles server broadcast of view mode change. Clears the message store
@@ -285,15 +375,19 @@ module TUI
         @scroll_offset = @max_scroll if @auto_scroll
         @scroll_offset = @scroll_offset.clamp(0, @max_scroll)
 
-        widget = base_widget.with(
-          scroll: [@scroll_offset, 0],
-          block: tui.block(
-            title: "Chat",
-            borders: [:all],
-            border_type: :rounded,
-            border_style: {fg: "cyan"}
-          )
-        )
+        chat_block = {
+          title: "Chat",
+          borders: [:all],
+          border_type: :rounded,
+          border_style: @chat_focused ? {fg: "yellow"} : {fg: "cyan"}
+        }
+        if @chat_focused
+          chat_block[:titles] = [
+            {content: "\u2191\u2193 scroll  Esc return", position: :bottom, alignment: :center}
+          ]
+        end
+
+        widget = base_widget.with(scroll: [@scroll_offset, 0], block: tui.block(**chat_block))
         frame.render_widget(widget, area)
 
         return unless @max_scroll > 0
@@ -539,7 +633,7 @@ module TUI
         )
         frame.render_widget(widget, area)
 
-        return if disabled
+        return if disabled || @chat_focused
 
         cursor_x = area.x + 1 + @cursor_visual_col
         cursor_y = area.y + 1 + @cursor_visual_row - input_scroll
@@ -550,9 +644,15 @@ module TUI
       end
 
       def input_styles(tui, disabled)
+        border_color = if disabled || @chat_focused
+          "dark_gray"
+        else
+          "green"
+        end
+
         {
           text: disabled ? tui.style(fg: "dark_gray") : tui.style(fg: "white"),
-          border: disabled ? {fg: "dark_gray"} : {fg: "green"}
+          border: {fg: border_color}
         }
       end
 
@@ -661,6 +761,8 @@ module TUI
         return unless connected?
 
         text = @input_buffer.consume
+        save_to_history(text)
+        reset_history_browsing
         @input_scroll_offset = 0
         @cable_client.speak(text)
       end
@@ -681,6 +783,90 @@ module TUI
         true
       end
 
+      # Handles keyboard events when the chat pane has focus.
+      # Up/Down scroll the chat; all other keys are ignored.
+      #
+      # @return [Boolean] true if the event was handled
+      def handle_chat_focused_event(event)
+        if event.up?
+          scroll_up(SCROLL_STEP)
+          true
+        elsif event.down?
+          scroll_down(SCROLL_STEP)
+          true
+        else
+          false
+        end
+      end
+
+      # Navigates backward through input history (older entries).
+      # On first invocation, saves the current input buffer so it can be
+      # restored when the user navigates past the newest entry.
+      #
+      # @return [Boolean] true if a history entry was loaded
+      def navigate_history_back
+        return false if @input_history.empty?
+
+        if @history_index.nil?
+          @saved_input = @input_buffer.text
+          @history_index = @input_history.size - 1
+        elsif @history_index > 0
+          @history_index -= 1
+        else
+          return false
+        end
+
+        load_history_entry(@input_history[@history_index])
+        true
+      end
+
+      # Navigates forward through input history (newer entries).
+      # When navigating past the newest entry, restores the text that was
+      # in the input buffer before history browsing started.
+      #
+      # @return [Boolean] true if navigated, false if not browsing history
+      def navigate_history_forward
+        return false if @history_index.nil?
+
+        @history_index += 1
+
+        if @history_index >= @input_history.size
+          load_history_entry(@saved_input)
+          reset_history_browsing
+        else
+          load_history_entry(@input_history[@history_index])
+        end
+
+        true
+      end
+
+      # Replaces the input buffer content with a history entry.
+      # Cursor is placed at the end of the text.
+      #
+      # @param text [String] history entry or saved input to load
+      # @return [void]
+      def load_history_entry(text)
+        @input_buffer.clear
+        @input_buffer.insert(text)
+      end
+
+      # Exits history browsing mode without changing the input buffer.
+      # @return [void]
+      def reset_history_browsing
+        @history_index = nil
+        @saved_input = nil
+      end
+
+      # Appends a message to input history, skipping consecutive duplicates.
+      #
+      # @param text [String] submitted message text
+      # @return [void]
+      def save_to_history(text)
+        return if @input_history.last == text
+
+        @input_history << text
+      end
+
       # Dispatches arrow and page keys to {#scroll_up} or {#scroll_down}.
       # @return [true] always redraws after scrolling
       def handle_scroll_key(event)
@@ -737,6 +923,7 @@ module TUI
       def handle_paste_event(event)
         return false if @input_buffer.full?
 
+        reset_history_browsing
         @input_buffer.insert(event.content)
       end
 

data/lib/workflows/definition.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Workflows
+  class InvalidDefinitionError < StandardError; end
+
+  # A workflow parsed from a Markdown definition file.
+  # YAML frontmatter holds metadata; the Markdown body contains free-form
+  # instructions that the analytical brain reads and converts into goals.
+  #
+  # Workflows are operational recipes — they describe WHAT to do step by
+  # step. The analytical brain uses judgment to decompose workflow prose
+  # into tracked goals based on the user's specific context.
+  #
+  # @example Workflow file format
+  #   ---
+  #   name: feature
+  #   description: "Implement a GitHub issue end-to-end."
+  #   ---
+  #
+  #   ## Context
+  #   Create and complete a new feature...
+  class Definition
+    # @return [String] unique workflow identifier used in read_workflow(name: "...")
+    attr_reader :name
+
+    # @return [String] description shown to the analytical brain for relevance matching
+    attr_reader :description
+
+    # @return [String] workflow content (Markdown body) — free-form instructions
+    attr_reader :content
+
+    # @return [String] file path this definition was loaded from
+    attr_reader :source_path
+
+    def initialize(name:, description:, content:, source_path: "")
+      @name = name
+      @description = description
+      @content = content
+      @source_path = source_path
+    end
+
+    # Parses a Markdown file with YAML frontmatter into a Definition.
+    #
+    # @param path [String, Pathname] path to the .md file
+    # @return [Definition]
+    # @raise [InvalidDefinitionError] if required fields are missing or frontmatter is malformed
+    def self.from_file(path)
+      raw = File.read(path)
+      frontmatter, body = parse_frontmatter(raw)
+
+      validate_required_fields!(frontmatter, path)
+
+      new(
+        name: frontmatter["name"].to_s.strip,
+        description: frontmatter["description"].to_s.strip,
+        content: body.strip,
+        source_path: path.to_s
+      )
+    end
+
+    # @param raw [String] raw file content with YAML frontmatter
+    # @return [Array(Hash, String)] parsed frontmatter and body text
+    # @raise [InvalidDefinitionError] if frontmatter is missing or malformed
+    def self.parse_frontmatter(raw)
+      # Opening "---" must be followed by a newline (not just whitespace).
+      # Non-greedy (.*?\n) captures YAML lines up to the closing "---".
+      # Closing "---" may optionally be followed by a newline before the body.
+      # The /m flag lets (.*) in the body capture across newlines.
+      match = raw.match(/\A---\s*\n(.*?\n)---\s*\n?(.*)\z/m)
+      raise InvalidDefinitionError, "Missing YAML frontmatter" unless match
+
+      frontmatter = YAML.safe_load(match[1])
+      raise InvalidDefinitionError, "Frontmatter is not a valid YAML mapping" unless frontmatter.is_a?(Hash)
+
+      [frontmatter, match[2]]
+    end
+
+    NAME_FORMAT = /\A[a-z0-9][a-z0-9_-]*\z/
+
+    def self.validate_required_fields!(frontmatter, path)
+      %w[name description].each do |field|
+        value = frontmatter[field].to_s.strip
+        raise InvalidDefinitionError, "Missing required field '#{field}' in #{path}" if value.empty?
+      end
+
+      name = frontmatter["name"].to_s.strip
+      unless name.match?(NAME_FORMAT)
+        raise InvalidDefinitionError,
+          "Invalid workflow name '#{name}' in #{path} — must be lowercase alphanumeric with hyphens/underscores"
+      end
+    end
+
+    private_class_method :parse_frontmatter, :validate_required_fields!
+  end
+end

data/lib/workflows/registry.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Workflows
+  # Loads workflow definitions from Markdown files and provides lookup.
+  # Scans two directories:
+  #   1. Built-in workflows shipped with Anima (workflows/ in the gem root)
+  #   2. User-defined workflows (~/.anima/workflows/)
+  # User workflows override built-in ones when names collide.
+  class Registry
+    # @return [Hash{String => Definition}] loaded definitions keyed by name
+    attr_reader :workflows
+
+    BUILTIN_DIR = File.expand_path("../../workflows", __dir__).freeze
+    USER_DIR = File.expand_path("~/.anima/workflows").freeze
+
+    def initialize
+      @workflows = {}
+    end
+
+    # Returns the global registry, lazily loaded on first access.
+    #
+    # @return [Registry]
+    def self.instance
+      @instance ||= new.load_all
+    end
+
+    # Reloads the global registry from disk.
+    #
+    # @return [Registry]
+    def self.reload!
+      @instance = new.load_all
+    end
+
+    # Loads definitions from both built-in and user directories.
+    # User definitions override built-in ones with the same name.
+    #
+    # @return [self]
+    def load_all
+      load_directory(BUILTIN_DIR)
+      load_directory(USER_DIR)
+      self
+    end
+
+    # Loads workflow definitions from a single directory (flat .md files only).
+    #
+    # @param dir [String] directory path to scan for workflow definitions
+    # @return [void]
+    def load_directory(dir)
+      return unless Dir.exist?(dir)
+
+      Dir.glob(File.join(dir, "*.md")).sort.each do |path|
+        definition = Definition.from_file(path)
+        @workflows[definition.name] = definition
+      rescue InvalidDefinitionError => error
+        Rails.logger.warn("Skipping invalid workflow definition #{path}: #{error.message}")
+      end
+    end
+
+    # Looks up a named workflow definition.
+    #
+    # @param name [String] workflow name
+    # @return [Definition, nil]
+    def find(name)
+      @workflows[name]
+    end
+
+    # Workflow names and descriptions for inclusion in the analytical brain's context.
+    #
+    # @return [Hash{String => String}] name => description
+    def catalog
+      @workflows.transform_values(&:description)
+    end
+
+    # @return [Array<String>] registered workflow names
+    def available_names
+      @workflows.keys
+    end
+
+    # @return [Boolean]
+    def any?
+      @workflows.any?
+    end
+
+    # @return [Integer]
+    def size
+      @workflows.size
+    end
+  end
+end