anima-core 0.0.1 → 0.1.0

data/lib/tools/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Tools
+  # Abstract base class for all Anima tools. Subclasses must implement
+  # the class-level schema methods and the instance-level {#execute} method.
+  #
+  # @abstract Subclass and implement {.tool_name}, {.description},
+  #   {.input_schema}, and {#execute}
+  #
+  # @example Implementing a tool
+  #   class Tools::Echo < Tools::Base
+  #     def self.tool_name = "echo"
+  #     def self.description = "Echoes input back"
+  #     def self.input_schema
+  #       {type: "object", properties: {text: {type: "string"}}, required: ["text"]}
+  #     end
+  #
+  #     def execute(input)
+  #       input["text"]
+  #     end
+  #   end
+  class Base
+    class << self
+      # @return [String] unique tool identifier sent to the LLM
+      def tool_name
+        raise NotImplementedError, "#{self} must implement .tool_name"
+      end
+
+      # @return [String] human-readable description for the LLM
+      def description
+        raise NotImplementedError, "#{self} must implement .description"
+      end
+
+      # @return [Hash] JSON Schema describing the tool's input parameters
+      def input_schema
+        raise NotImplementedError, "#{self} must implement .input_schema"
+      end
+
+      # Builds the schema hash expected by the Anthropic tools API.
+      # @return [Hash] with :name, :description, and :input_schema keys
+      def schema
+        {name: tool_name, description: description, input_schema: input_schema}
+      end
+    end
+
+    # Accepts and discards context keywords so that the Registry can pass
+    # shared dependencies (e.g. shell_session) to any tool uniformly.
+    # Subclasses that need specific context should override with named kwargs.
+    def initialize(**) = nil
+
+    # Execute the tool with the given input.
+    # @param input [Hash] parsed input matching {.input_schema}
+    # @return [String, Hash] result content; Hash with :error key signals failure
+    def execute(input)
+      raise NotImplementedError, "#{self.class} must implement #execute"
+    end
+  end
+end

data/lib/tools/bash.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Tools
+  # Executes bash commands in a persistent {ShellSession}. Commands share
+  # working directory, environment variables, and shell history within a
+  # conversation. Output is truncated and timeouts are enforced by the
+  # underlying session.
+  #
+  # @see ShellSession#run
+  class Bash < Base
+    def self.tool_name = "bash"
+
+    def self.description = "Execute a bash command. Working directory and environment persist across calls within a conversation."
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          command: {type: "string", description: "The bash command to execute"}
+        },
+        required: ["command"]
+      }
+    end
+
+    # @param shell_session [ShellSession] persistent shell backing this tool
+    def initialize(shell_session:, **)
+      @shell_session = shell_session
+    end
+
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @return [String] formatted output with stdout, stderr, and exit code
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      command = input["command"].to_s
+      return {error: "Command cannot be blank"} if command.strip.empty?
+
+      result = @shell_session.run(command)
+      return result if result.key?(:error)
+
+      format_result(result[:stdout], result[:stderr], result[:exit_code])
+    end
+
+    private
+
+    def format_result(stdout, stderr, exit_code)
+      parts = []
+      parts << "stdout:\n#{stdout}" unless stdout.empty?
+      parts << "stderr:\n#{stderr}" unless stderr.empty?
+      parts << "exit_code: #{exit_code}"
+      parts.join("\n\n")
+    end
+  end
+end

data/lib/tools/registry.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Tools
+  class UnknownToolError < StandardError; end
+
+  # Manages tool registration, schema export, and dispatch.
+  # Tools are registered by class and looked up by name at execution time.
+  # An optional context hash is passed to each tool's constructor, allowing
+  # shared dependencies (e.g. a {ShellSession}) to reach tools that need them.
+  #
+  # @example
+  #   registry = Tools::Registry.new(context: {shell_session: my_shell})
+  #   registry.register(Tools::Bash)
+  #   registry.execute("bash", {"command" => "ls"})
+  class Registry
+    # @return [Hash{String => Class}] registered tool classes keyed by name
+    attr_reader :tools
+
+    # @param context [Hash] keyword arguments forwarded to every tool constructor
+    def initialize(context: {})
+      @tools = {}
+      @context = context
+    end
+
+    # Register a tool class. The class must respond to .tool_name.
+    # @param tool_class [Class<Tools::Base>] the tool class to register
+    # @return [void]
+    def register(tool_class)
+      @tools[tool_class.tool_name] = tool_class
+    end
+
+    # @return [Array<Hash>] schema array for the Anthropic tools API parameter
+    def schemas
+      @tools.values.map(&:schema)
+    end
+
+    # Instantiate and execute a tool by name. The registry's context is
+    # forwarded to the tool constructor as keyword arguments.
+    #
+    # @param name [String] registered tool name
+    # @param input [Hash] tool input parameters
+    # @return [String, Hash] tool execution result
+    # @raise [UnknownToolError] if no tool is registered with the given name
+    def execute(name, input)
+      tool_class = @tools.fetch(name) { raise UnknownToolError, "Unknown tool: #{name}" }
+      tool_class.new(**@context).execute(input)
+    end
+
+    # @param name [String] tool name to check
+    # @return [Boolean] whether a tool with the given name is registered
+    def registered?(name)
+      @tools.key?(name)
+    end
+
+    # @return [Boolean] whether any tools are registered
+    def any?
+      @tools.any?
+    end
+  end
+end

data/lib/tools/web_get.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "httparty"
+
+module Tools
+  # Fetches content from a URL via HTTP GET. Returns the response body
+  # as plain text, truncated to {MAX_RESPONSE_BYTES} to prevent memory issues.
+  #
+  # Only http and https schemes are allowed.
+  class WebGet < Base
+    MAX_RESPONSE_BYTES = 100_000
+    REQUEST_TIMEOUT = 10
+
+    def self.tool_name = "web_get"
+
+    def self.description = "Fetch content from a URL via HTTP GET and return the response body"
+
+    def self.input_schema
+      {
+        type: "object",
+        properties: {
+          url: {type: "string", description: "The URL to fetch (http or https)"}
+        },
+        required: ["url"]
+      }
+    end
+
+    # @param input [Hash<String, Object>] string-keyed hash from the Anthropic API
+    # @return [String] response body (possibly truncated)
+    # @return [Hash] with :error key on failure
+    def execute(input)
+      validate_and_fetch(input["url"].to_s)
+    end
+
+    private
+
+    def validate_and_fetch(url)
+      scheme = URI.parse(url).scheme
+
+      unless %w[http https].include?(scheme)
+        return {error: "Only http and https URLs are supported, got: #{scheme.inspect}"}
+      end
+
+      truncate_body(HTTParty.get(url, timeout: REQUEST_TIMEOUT, follow_redirects: false).body.to_s)
+    rescue URI::InvalidURIError => error
+      {error: "Invalid URL: #{error.message}"}
+    rescue Net::OpenTimeout, Net::ReadTimeout
+      {error: "Request timed out after #{REQUEST_TIMEOUT} seconds"}
+    rescue Errno::ECONNREFUSED
+      {error: "Connection refused: #{url}"}
+    rescue => error
+      {error: "#{error.class}: #{error.message}"}
+    end
+
+    def truncate_body(body)
+      return body if body.bytesize <= MAX_RESPONSE_BYTES
+
+      body.byteslice(0, MAX_RESPONSE_BYTES) +
+        "\n\n[Truncated: response exceeded #{MAX_RESPONSE_BYTES} bytes]"
+    end
+  end
+end

data/lib/tui/app.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require_relative "screens/chat"
+require_relative "screens/settings"
+require_relative "screens/anthropic"
+
+module TUI
+  class App
+    SCREENS = %i[chat settings anthropic].freeze
+
+    COMMAND_KEYS = {
+      "n" => :new_session,
+      "s" => :settings,
+      "a" => :anthropic,
+      "q" => :quit
+    }.freeze
+
+    MENU_LABELS = COMMAND_KEYS.map { |key, action| "[#{key}] #{action.capitalize}" }.freeze
+
+    SIDEBAR_WIDTH = 28
+
+    attr_reader :current_screen, :command_mode
+
+    def initialize
+      @current_screen = :chat
+      @command_mode = false
+      @screens = {
+        chat: Screens::Chat.new,
+        settings: Screens::Settings.new,
+        anthropic: Screens::Anthropic.new
+      }
+    end
+
+    def run
+      RatatuiRuby.run do |tui|
+        loop do
+          tui.draw { |frame| render(frame, tui) }
+
+          break if handle_event(tui.poll_event) == :quit
+        end
+      end
+    end
+
+    private
+
+    def render(frame, tui)
+      main_area, sidebar = tui.split(
+        frame.area,
+        direction: :horizontal,
+        constraints: [
+          tui.constraint_fill(1),
+          tui.constraint_length(SIDEBAR_WIDTH)
+        ]
+      )
+
+      content_area, status_bar = tui.split(
+        main_area,
+        direction: :vertical,
+        constraints: [
+          tui.constraint_fill(1),
+          tui.constraint_length(1)
+        ]
+      )
+
+      @screens[@current_screen].render(frame, content_area, tui)
+      render_sidebar(frame, sidebar, tui)
+      render_status_bar(frame, status_bar, tui)
+    end
+
+    def render_sidebar(frame, area, tui)
+      if @command_mode
+        render_menu(frame, area, tui)
+      else
+        render_info(frame, area, tui)
+      end
+    end
+
+    def render_menu(frame, area, tui)
+      menu = tui.list(
+        items: MENU_LABELS,
+        block: tui.block(
+          title: "Command",
+          borders: [:all],
+          border_type: :rounded,
+          border_style: {fg: "yellow"}
+        )
+      )
+      frame.render_widget(menu, area)
+    end
+
+    def render_info(frame, area, tui)
+      info_text = tui.line(spans: [
+        tui.span(content: "Anima v#{Anima::VERSION}", style: tui.style(fg: "white"))
+      ])
+      hint_text = tui.line(spans: [
+        tui.span(content: "Ctrl+a", style: tui.style(fg: "cyan", modifiers: [:bold])),
+        tui.span(content: " command mode", style: tui.style(fg: "dark_gray"))
+      ])
+
+      info = tui.paragraph(
+        text: [info_text, hint_text],
+        block: tui.block(
+          title: "Info",
+          borders: [:all],
+          border_type: :rounded,
+          border_style: {fg: "white"}
+        )
+      )
+      frame.render_widget(info, area)
+    end
+
+    def render_status_bar(frame, area, tui)
+      mode_span = if @command_mode
+        tui.span(content: " COMMAND ", style: tui.style(fg: "black", bg: "yellow", modifiers: [:bold]))
+      elsif chat_loading?
+        tui.span(content: " THINKING ", style: tui.style(fg: "black", bg: "magenta", modifiers: [:bold]))
+      else
+        tui.span(content: " NORMAL ", style: tui.style(fg: "black", bg: "cyan", modifiers: [:bold]))
+      end
+
+      widget = tui.paragraph(text: tui.line(spans: [mode_span]))
+      frame.render_widget(widget, area)
+    end
+
+    def chat_loading?
+      @screens[:chat].loading?
+    end
+
+    def handle_event(event)
+      return nil if event.none?
+      return :quit if event.ctrl_c?
+
+      if @command_mode
+        handle_command_mode(event)
+      else
+        handle_normal_mode(event)
+      end
+    end
+
+    def handle_command_mode(event)
+      @command_mode = false
+
+      return nil unless event.key?
+
+      action = COMMAND_KEYS[event.code]
+      case action
+      when :quit
+        :quit
+      when :new_session
+        @screens[:chat].new_session
+        @current_screen = :chat
+        nil
+      when :settings, :anthropic
+        @current_screen = action
+        nil
+      end
+    end
+
+    def handle_normal_mode(event)
+      return nil unless event.key?
+
+      if ctrl_a?(event)
+        @command_mode = true
+        return nil
+      end
+
+      if event.esc? && @current_screen != :chat
+        @current_screen = :chat
+        return nil
+      end
+
+      screen = @screens[@current_screen]
+      screen.handle_event(event) if screen.respond_to?(:handle_event)
+      nil
+    end
+
+    def ctrl_a?(event)
+      event.code == "a" && event.modifiers&.include?("ctrl")
+    end
+  end
+end

data/lib/tui/screens/anthropic.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module TUI
+  module Screens
+    class Anthropic
+      def render(frame, area, tui)
+        widget = tui.paragraph(
+          text: "Anthropic account connection will be configured here.",
+          alignment: :center,
+          wrap: true,
+          block: tui.block(
+            title: "Anthropic Connection",
+            titles: [
+              {content: "Esc back", position: :bottom, alignment: :center}
+            ],
+            borders: [:all],
+            border_type: :rounded,
+            border_style: {fg: "magenta"}
+          )
+        )
+        frame.render_widget(widget, area)
+      end
+    end
+  end
+end

data/lib/tui/screens/chat.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+module TUI
+  module Screens
+    class Chat
+      INPUT_HEIGHT = 3
+      MAX_INPUT_LENGTH = 10_000
+      PRINTABLE_CHAR = /\A[[:print:]]\z/
+
+      ROLE_USER = "user"
+      ROLE_ASSISTANT = "assistant"
+      ROLE_LABELS = {ROLE_USER => "You", ROLE_ASSISTANT => "Anima"}.freeze
+
+      attr_reader :input, :message_collector, :session
+
+      def initialize(message_collector: nil, persister: nil, session: nil, shell_session: nil)
+        @message_collector = message_collector || Events::Subscribers::MessageCollector.new
+        @input = ""
+        @loading = false
+        @client = nil
+        @submit_thread = nil
+
+        @session = session || Session.order(id: :desc).first || Session.create!
+        load_session_messages
+        @persister = persister || Events::Subscribers::Persister.new(@session)
+        @shell_session = shell_session || ShellSession.new(session_id: @session.id)
+
+        Events::Bus.subscribe(@message_collector)
+        Events::Bus.subscribe(@persister)
+      end
+
+      def messages
+        @message_collector.messages
+      end
+
+      def render(frame, area, tui)
+        chat_area, input_area = tui.split(
+          area,
+          direction: :vertical,
+          constraints: [
+            tui.constraint_fill(1),
+            tui.constraint_length(INPUT_HEIGHT)
+          ]
+        )
+
+        render_messages(frame, chat_area, tui)
+        render_input(frame, input_area, tui)
+      end
+
+      def handle_event(event)
+        return false if @loading
+
+        if event.enter?
+          submit_message
+          true
+        elsif event.backspace?
+          @input = @input.chop
+          true
+        elsif printable_char?(event) && @input.length < MAX_INPUT_LENGTH
+          @input += event.code
+          true
+        else
+          false
+        end
+      end
+
+      def new_session
+        @submit_thread&.join
+        @shell_session&.finalize
+        @session = Session.create!
+        @persister.session = @session
+        @message_collector.clear
+        @input = ""
+        @loading = false
+        @shell_session = ShellSession.new(session_id: @session.id)
+        @registry = nil
+      end
+
+      def finalize
+        @submit_thread&.join
+        @shell_session&.finalize
+        Events::Bus.unsubscribe(@message_collector)
+        Events::Bus.unsubscribe(@persister)
+      end
+
+      def loading?
+        @loading
+      end
+
+      private
+
+      def render_messages(frame, area, tui)
+        lines = build_message_lines(tui)
+
+        if @loading
+          lines << tui.line(spans: [
+            tui.span(content: "Thinking...", style: tui.style(fg: "yellow", modifiers: [:bold]))
+          ])
+        end
+
+        if lines.empty?
+          lines << tui.line(spans: [
+            tui.span(content: "Type a message to start chatting.", style: tui.style(fg: "dark_gray"))
+          ])
+        end
+
+        widget = tui.paragraph(
+          text: lines,
+          wrap: true,
+          block: tui.block(
+            title: "Chat",
+            borders: [:all],
+            border_type: :rounded,
+            border_style: {fg: "cyan"}
+          )
+        )
+        frame.render_widget(widget, area)
+      end
+
+      def build_message_lines(tui)
+        messages.flat_map do |msg|
+          role_style = if msg[:role] == ROLE_USER
+            tui.style(fg: "green", modifiers: [:bold])
+          else
+            tui.style(fg: "cyan", modifiers: [:bold])
+          end
+
+          label = ROLE_LABELS.fetch(msg[:role], msg[:role])
+
+          [
+            tui.line(spans: [
+              tui.span(content: "#{label}: ", style: role_style),
+              tui.span(content: msg[:content], style: tui.style(fg: "white"))
+            ]),
+            tui.line(spans: [tui.span(content: "", style: tui.style(fg: "white"))])
+          ]
+        end
+      end
+
+      def render_input(frame, area, tui)
+        cursor = @loading ? "" : "\u2588"
+        border_style = @loading ? {fg: "dark_gray"} : {fg: "green"}
+        text_style = @loading ? tui.style(fg: "dark_gray") : tui.style(fg: "white")
+
+        widget = tui.paragraph(
+          text: tui.line(spans: [
+            tui.span(content: "> #{@input}#{cursor}", style: text_style)
+          ]),
+          block: tui.block(
+            title: @loading ? "Waiting..." : "Input",
+            titles: @loading ? [] : [
+              {content: "Enter send", position: :bottom, alignment: :center}
+            ],
+            borders: [:all],
+            border_type: :rounded,
+            border_style: border_style
+          )
+        )
+        frame.render_widget(widget, area)
+      end
+
+      def submit_message
+        text = @input.strip
+        return if text.empty?
+
+        Events::Bus.emit(Events::UserMessage.new(content: text, session_id: @session.id))
+        @input = ""
+        @loading = true
+
+        @submit_thread = Thread.new do
+          @client ||= LLM::Client.new
+          @registry ||= build_tool_registry
+          viewport_messages = @session.messages_for_llm
+          response = @client.chat_with_tools(
+            viewport_messages,
+            registry: @registry,
+            session_id: @session.id
+          )
+          Events::Bus.emit(Events::AgentMessage.new(content: response, session_id: @session.id))
+        rescue => e
+          Events::Bus.emit(Events::AgentMessage.new(content: "Error: #{e.message}", session_id: @session.id))
+        ensure
+          @loading = false
+        end
+      end
+
+      def build_tool_registry
+        registry = Tools::Registry.new(context: {shell_session: @shell_session})
+        registry.register(Tools::WebGet)
+        registry.register(Tools::Bash)
+        registry
+      end
+
+      def load_session_messages
+        @session.events.where(event_type: Events::Subscribers::MessageCollector::DISPLAYABLE_TYPES).each do |event|
+          @message_collector.messages_push({
+            role: Events::Subscribers::MessageCollector::ROLE_MAP.fetch(event.event_type),
+            content: event.payload["content"].to_s
+          })
+        end
+      end
+
+      def printable_char?(event)
+        return false if event.modifiers&.include?("ctrl")
+
+        event.code.length == 1 && event.code.match?(PRINTABLE_CHAR)
+      end
+    end
+  end
+end

data/lib/tui/screens/settings.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module TUI
+  module Screens
+    class Settings
+      MENU_ITEMS = [
+        "General",
+        "Appearance",
+        "Keybindings"
+      ].freeze
+
+      def initialize
+        # Initialized on first render — requires tui context from RatatuiRuby.run block
+        @list_state = nil
+      end
+
+      def render(frame, area, tui)
+        @list_state ||= tui.list_state(0)
+
+        list = tui.list(
+          items: MENU_ITEMS,
+          highlight_style: {fg: "yellow", bold: true},
+          highlight_symbol: "> ",
+          block: tui.block(
+            title: "Settings",
+            titles: [
+              {content: "↑/↓ navigate • Esc back", position: :bottom, alignment: :center}
+            ],
+            borders: [:all],
+            border_type: :rounded,
+            border_style: {fg: "green"}
+          )
+        )
+        frame.render_stateful_widget(list, area, @list_state)
+      end
+
+      def handle_event(event)
+        return false unless @list_state
+
+        if event.down? || event.j?
+          @list_state.select_next
+          true
+        elsif event.up? || event.k?
+          @list_state.select_previous
+          true
+        else
+          false
+        end
+      end
+    end
+  end
+end