anima-core 0.2.1 → 1.0.0

data/lib/tui/screens/chat.rb

@@ -16,6 +16,7 @@ module TUI
       MOUSE_SCROLL_STEP = 2
 
       TOOL_ICON = "\u{1F527}"
+      CLOCK_ICON = "\u{1F552}"
       CHECKMARK = "\u2713"
       RETURN_ARROW = "\u21A9"
       ERROR_ICON = "\u274C"
@@ -26,7 +27,9 @@ module TUI
       # independent of Rails. Must stay in sync when adding new modes.
       VIEW_MODES = %w[basic verbose debug].freeze
 
-      attr_reader :message_store, :scroll_offset, :session_info, :view_mode
+      attr_reader :message_store, :scroll_offset, :session_info, :view_mode, :sessions_list,
+        :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
@@ -41,7 +44,15 @@ module TUI
         @max_scroll = 0
         @input_scroll_offset = 0
         @view_mode = "basic"
-        @session_info = {id: cable_client.session_id, 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
@@ -76,23 +87,40 @@ module TUI
         render_input(frame, input_area, tui)
       end
 
-      # Scrolling and cursor navigation bypass the loading guard so users can
-      # read chat history during LLM calls.
+      # 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_scroll_key(event) if event.up? || event.down?
 
-        return false if @loading
+        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 navigate_history_back
+        end
+
+        if event.down?
+          return true if @input_buffer.move_down
+          return navigate_history_forward
+        end
 
         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?
@@ -104,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
@@ -118,13 +147,36 @@ module TUI
         @cable_client.create_session
       end
 
-      # Cycles to the next view mode and requests the server to switch.
+      # Switches to an existing session through the WebSocket protocol.
+      # The brain switches the channel stream and sends a session_changed
+      # signal followed by chat history.
+      #
+      # @param session_id [Integer] target session to switch to
+      def switch_session(session_id)
+        @cable_client.switch_session(session_id)
+      end
+
+      # Sends an explicit view mode switch command to the server.
       # The server broadcasts the mode change and re-transmits the viewport
       # decorated in the new mode to all connected clients.
-      def cycle_view_mode
-        current_index = VIEW_MODES.index(@view_mode) || 0
-        next_mode = VIEW_MODES[(current_index + 1) % VIEW_MODES.size]
-        @cable_client.change_view_mode(next_mode)
+      #
+      # @param mode [String] target view mode ("basic", "verbose", or "debug")
+      def switch_view_mode(mode)
+        @cable_client.change_view_mode(mode)
+      end
+
+      # Clears the authentication_required flag after the App has consumed it.
+      # @return [void]
+      def clear_authentication_required
+        @authentication_required = false
+      end
+
+      # Returns and clears the token save result for one-shot consumption by the App.
+      # @return [Hash, nil] {success: true} or {success: false, message: "..."}, or nil
+      def consume_token_save_result
+        result = @token_save_result
+        @token_save_result = nil
+        result
       end
 
       def finalize
@@ -134,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
@@ -149,8 +213,25 @@ 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"
+            @message_store.remove_by_id(msg["event_id"]) if msg["event_id"]
+          when "authentication_required"
+            @authentication_required = true
+          when "token_saved"
+            @authentication_required = false
+            @token_save_result = {success: true}
+          when "token_error"
+            @token_save_result = {success: false, message: msg["message"]}
           when "error"
             # Silently ignored — no user-facing error display yet
           else
@@ -159,25 +240,45 @@ module TUI
               handle_connection_status(msg)
             when "user_message"
               @message_store.process_event(msg)
-              @session_info[:message_count] += 1
-              @loading = true
+              unless action == "update"
+                @session_info[:message_count] += 1
+                @loading = true
+              end
             when "agent_message"
               @message_store.process_event(msg)
-              @session_info[:message_count] += 1
-              @loading = false
+              unless action == "update"
+                @session_info[:message_count] += 1
+                @loading = false
+              end
             else # tool_call, tool_response, and other event types
               @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 on (re)subscription so fresh history from the server
-      # replaces any messages displayed before the disconnect.
+      # Clears stale state when subscription begins so the store is empty
+      # before history arrives. Action Cable sends confirm_subscription
+      # AFTER transmit calls in the subscribed callback, so clearing on
+      # "subscribed" would wipe history that already arrived.
       def handle_connection_status(msg)
         case msg["status"]
-        when "subscribed"
+        when "subscribing"
           @message_store.clear
           @loading = false
           @session_info[:message_count] = 0
@@ -191,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
@@ -230,25 +368,26 @@ module TUI
         inner_width = [area.width - 2, 1].max
         @visible_height = [area.height - 2, 0].max
 
-        content_widget = tui.paragraph(text: lines, wrap: true, style: tui.style(fg: "white"))
-        content_height = content_widget.line_count(inner_width)
+        base_widget = tui.paragraph(text: lines, wrap: true, style: tui.style(fg: "white"))
+        content_height = base_widget.line_count(inner_width)
 
         @max_scroll = [content_height - @visible_height, 0].max
         @scroll_offset = @max_scroll if @auto_scroll
         @scroll_offset = @scroll_offset.clamp(0, @max_scroll)
 
-        widget = tui.paragraph(
-          text: lines,
-          wrap: true,
-          style: tui.style(fg: "white"),
-          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
@@ -325,14 +464,18 @@ module TUI
       end
 
       # Renders a user or assistant message with optional timestamp and token count.
+      # Pending messages are dimmed with a clock icon to indicate they haven't
+      # been sent to the LLM yet.
       # @param tui [RatatuiRuby] TUI rendering API
       # @param data [Hash] structured data with "role", "content", and optional
-      #   "timestamp", "tokens", "estimated"
+      #   "timestamp", "tokens", "estimated", "status"
       # @param role [String] "user" or "assistant"
       # @return [Array<RatatuiRuby::Widgets::Line>]
       def render_conversation_entry(tui, data, role)
-        color = ROLE_COLORS.fetch(role, "white")
+        pending = data["status"] == "pending"
+        color = pending ? "dark_gray" : ROLE_COLORS.fetch(role, "white")
         prefix = ROLE_LABELS.fetch(role, role)
+        prefix = "#{CLOCK_ICON} #{prefix}" if pending
         style = tui.style(fg: color)
 
         meta = []
@@ -464,7 +607,7 @@ module TUI
       end
 
       def render_input(frame, area, tui)
-        disabled = @loading || !connected?
+        disabled = !connected?
         styles = input_styles(tui, disabled)
 
         title = input_title
@@ -490,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
@@ -501,16 +644,20 @@ 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
 
       def input_title
-        if @loading
-          "Waiting..."
-        elsif !connected?
+        if !connected?
           "Disconnected"
         else
           "Input"
@@ -614,10 +761,112 @@ 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
 
+      # Recalls the last pending user message for editing. Removes it from
+      # the message store, puts its content back in the input buffer, and
+      # tells the server to delete the event.
+      #
+      # @return [Boolean] true if a message was recalled
+      def recall_pending_message
+        pending = @message_store.last_pending_user_message
+        return false unless pending
+
+        @message_store.remove_by_id(pending[:id])
+        @input_buffer.clear
+        @input_buffer.insert(pending[:content])
+        @cable_client.recall_pending(pending[:id])
+        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)
@@ -669,13 +918,12 @@ module TUI
       end
 
       # Inserts pasted clipboard content at cursor position.
-      # Paste is dispatched before the generic loading guard in {#handle_event}
-      # but still blocked during loading to match the visually-disabled input.
       # @param event [RatatuiRuby::Event::Paste] paste event with content
-      # @return [Boolean] true if content was inserted, false if loading or buffer full
+      # @return [Boolean] true if content was inserted, false if buffer full
       def handle_paste_event(event)
-        return false if @loading || @input_buffer.full?
+        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