octo-agent 0.11.2

data/lib/octo/agent/tool_executor.rb

@@ -0,0 +1,454 @@
+# frozen_string_literal: true
+
+module Octo
+  class Agent
+    # Tool execution and permission management
+    # Handles tool confirmation, preview, and result building
+    module ToolExecutor
+      # Check if a tool should be auto-executed based on permission mode
+      # @param tool_name [String] Name of the tool
+      # @param tool_params [Hash, String] Tool parameters
+      # @return [Boolean] true if should auto-execute
+      def should_auto_execute?(tool_name, tool_params = {})
+        case @config.permission_mode
+        when :auto_approve, :confirm_all
+          # Both modes auto-execute all file/shell tools without confirmation.
+          # The difference is only in request_user_feedback handling:
+          #   auto_approve → no human present, inject auto_reply
+          #   confirm_all  → human present, truly wait for user input
+          true
+        when :confirm_safes
+          # Use Security module to check auto-execution safety
+          is_safe_operation?(tool_name, tool_params)
+        else
+          false
+        end
+      end
+
+      # Check if an operation is considered safe for auto-execution
+      # @param tool_name [String] Name of the tool
+      # @param tool_params [Hash, String] Tool parameters
+      # @return [Boolean] true if safe operation
+      def is_safe_operation?(tool_name, tool_params = {})
+        # For terminal commands, defer to Security layer for the verdict.
+        if tool_name.to_s.downcase == 'terminal'
+          params = tool_params.is_a?(String) ? JSON.parse(tool_params) : tool_params
+          command = params[:command] || params['command']
+          # No command = session_id continuation / kill / action → safe by default.
+          return true unless command
+
+          return Octo::Tools::Security.command_safe_for_auto_execution?(command)
+        end
+
+        if tool_name.to_s.downcase == 'edit' || tool_name.to_s.downcase == 'write'
+          return false
+        end
+
+        true
+      end
+
+      # Request user confirmation for tool execution
+      # Shows preview and returns approval status
+      # @param call [Hash] Tool call with :name and :arguments
+      # @return [Hash] { approved: Boolean, feedback: String, system_injected: Boolean }
+      def confirm_tool_use?(call)
+        # Show preview first and check for errors
+        preview_error = show_tool_preview(call)
+
+        # If preview detected an error, auto-deny and provide feedback
+        if preview_error && preview_error[:error]
+          feedback = build_preview_error_feedback(call[:name], preview_error)
+          return { approved: false, feedback: feedback, system_injected: true }
+        end
+
+        # Request confirmation via UI
+        if @ui
+          prompt_text = format_tool_prompt(call)
+          result = @ui.request_confirmation(prompt_text, default: true)
+
+          case result
+          when true
+            { approved: true, feedback: nil }
+          when false, nil
+            # User denied - add visual marker based on tool type
+            tool_name_capitalized = call[:name].capitalize
+            @ui&.show_info("  ↳ #{tool_name_capitalized} cancelled", prefix_newline: false)
+            { approved: false, feedback: nil }
+          else
+            # String feedback - also add visual marker
+            tool_name_capitalized = call[:name].capitalize
+            @ui&.show_info("  ↳ #{tool_name_capitalized} cancelled", prefix_newline: false)
+            { approved: false, feedback: result.to_s }
+          end
+        else
+          # Fallback: auto-approve if no UI
+          { approved: true, feedback: nil }
+        end
+      end
+
+      # Show preview for tool execution
+      # @param call [Hash] Tool call with :name and :arguments
+      # @return [Hash, nil] Error information if preview detected issues
+      def show_tool_preview(call)
+        return nil unless @ui
+
+        begin
+          args = JSON.parse(call[:arguments], symbolize_names: true)
+
+          preview_error = nil
+          case call[:name]
+          when "write"
+            preview_error = show_write_preview(args)
+          when "edit"
+            preview_error = show_edit_preview(args)
+          # Shell and other tools don't need special preview
+          # They will be shown via show_tool_call in the main flow
+          end
+
+          preview_error
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      # Format tool call for user confirmation prompt
+      # @param call [Hash] Tool call with :name and :arguments
+      # @return [String] Formatted prompt text
+      def format_tool_prompt(call)
+        begin
+          args = JSON.parse(call[:arguments], symbolize_names: true)
+
+          # Try to use tool's format_call method for better formatting
+          tool = @tool_registry.get(call[:name]) rescue nil
+          if tool
+            formatted = tool.format_call(args) rescue nil
+            return formatted if formatted
+          end
+
+          # Fallback to manual formatting for common tools
+          case call[:name]
+          when "edit"
+            path = args[:path] || args[:file_path]
+            filename = Utils::PathHelper.safe_basename(path)
+            "Edit(#{filename})"
+          when "write"
+            filename = Utils::PathHelper.safe_basename(args[:path])
+            if args[:path] && File.exist?(args[:path])
+              "Write(#{filename}) - overwrite existing"
+            else
+              "Write(#{filename}) - create new"
+            end
+          when "terminal"
+            cmd = args[:command] || ''
+            display_cmd = cmd.length > 30 ? "#{cmd[0..27]}..." : cmd
+            "terminal(\"#{display_cmd}\")"
+          else
+            "Allow #{call[:name]}"
+          end
+        rescue JSON::ParserError
+          "Allow #{call[:name]}"
+        end
+      end
+
+      # Build success result for tool execution
+      # @param call [Hash] Tool call
+      # @param result [Object] Tool execution result
+      # @return [Hash] Formatted result for LLM
+      def build_success_result(call, result)
+        # Try to get tool instance to use its format_result_for_llm method
+        tool = @tool_registry.get(call[:name]) rescue nil
+
+        formatted_result = if tool && tool.respond_to?(:format_result_for_llm)
+          # Tool provides a custom LLM-friendly format
+          tool.format_result_for_llm(result)
+        else
+          # Fallback: use the original result
+          result
+        end
+
+        # Inject TODO reminder for non-todo_manager tools
+        formatted_result = inject_todo_reminder(call[:name], formatted_result)
+
+        # Extract image_inject sidecar before building the tool content string.
+        # image_inject carries the base64 payload that must be delivered as a
+        # follow-up `role:"user"` message (OpenAI/OpenRouter/Gemini only accept
+        # image_url blocks in user messages, not in tool messages).
+        # Strip it from the content sent to the API so it isn't tokenised as text.
+        image_inject = nil
+        if formatted_result.is_a?(Hash) && formatted_result[:image_inject]
+          image_inject = formatted_result[:image_inject]
+          formatted_result = formatted_result.reject { |k, _| k == :image_inject }
+          if formatted_result[:content_string]
+            formatted_result = formatted_result[:content_string]
+          end
+        end
+
+        # If the tool returned a plain string, use it directly (avoids double-escaping).
+        # If it returned an Array (e.g. multipart vision blocks with image + text),
+        # pass it through as-is so format_tool_results can send it to the API.
+        # Otherwise JSON-encode Hash/other values.
+        content = if formatted_result.is_a?(String)
+                    formatted_result
+                  elsif formatted_result.is_a?(Array)
+                    formatted_result
+                  else
+                    JSON.generate(formatted_result)
+                  end
+
+        result = { id: call[:id], content: content }
+        result[:image_inject] = image_inject if image_inject
+        result
+      end
+
+      # Build error result for tool execution
+      # @param call [Hash] Tool call
+      # @param error_message [String] Error message
+      # @return [Hash] Formatted error result
+      def build_error_result(call, error_message)
+        {
+          id: call[:id],
+          content: JSON.generate({ error: error_message })
+        }
+      end
+
+      # Build denied result when user denies tool execution
+      # @param call [Hash] Tool call
+      # @param user_feedback [String, nil] User's feedback message
+      # @param system_injected [Boolean] Whether this is a system-generated denial
+      # @return [Hash] Formatted denial result
+      def build_denied_result(call, user_feedback = nil, system_injected = false)
+        if system_injected
+          # System-generated feedback (e.g., from preview errors)
+          tool_content = {
+            error: "Tool #{call[:name]} denied: #{user_feedback}",
+            system_injected: true
+          }
+        else
+          # User manually denied or provided feedback
+          # Clearly state the action was NOT performed so the LLM knows the change did not happen
+          message = if user_feedback && !user_feedback.empty?
+                      "Tool use denied by user. This action was NOT performed. User feedback: #{user_feedback}"
+                    else
+                      "Tool use denied by user. This action was NOT performed."
+                    end
+
+          tool_content = {
+            error: message,
+            action_performed: false,
+            user_feedback: user_feedback
+          }
+        end
+
+        {
+          id: call[:id],
+          content: JSON.generate(tool_content)
+        }
+      end
+
+      # Check if a tool is potentially slow and should show progress
+      # @param tool_name [String] Name of the tool
+      # @param args [Hash] Tool arguments
+      # @return [Boolean] true if tool is potentially slow
+      private def potentially_slow_tool?(tool_name, args)
+        case tool_name.to_s.downcase
+        when 'terminal'
+          # Check if the command is a slow command
+          command = args[:command] || args['command']
+          return false unless command
+
+          # List of slow command patterns
+          slow_patterns = [
+            /bundle\s+(install|exec\s+rspec|exec\s+rake)/,
+            /npm\s+(install|run\s+test|run\s+build)/,
+            /yarn\s+(install|test|build)/,
+            /pnpm\s+install/,
+            /cargo\s+(build|test)/,
+            /go\s+(build|test)/,
+            /make\s+(test|build)/,
+            /pytest/,
+            /jest/,
+            /sleep\s+\d+/
+          ]
+
+          slow_patterns.any? { |pattern| command.match?(pattern) }
+        when 'web_fetch', 'web_search'
+          true
+        else
+          false
+        end
+      end
+
+      private def build_tool_progress_message(tool_name, args)
+        case tool_name.to_s.downcase
+        when 'terminal'
+          "Running command"
+        when 'web_fetch'
+          "Fetching web page"
+        when 'web_search'
+          "Searching web"
+        else
+          "Executing #{tool_name}"
+        end
+      end
+
+      # Inject TODO reminder into tool results for non-todo_manager tools
+      # This helps AI remember to mark TODOs as complete after executing tasks
+      # @param tool_name [String] Name of the tool
+      # @param result [Object] Tool execution result
+      # @return [Object] Result with optional TODO reminder
+      private def inject_todo_reminder(tool_name, result)
+        # Skip injection for todo_manager tool itself to avoid redundancy
+        return result if tool_name == "todo_manager"
+
+        # Get pending TODOs
+        todo_tool = @tool_registry.get("todo_manager")
+        return result unless todo_tool
+
+        pending_todos = begin
+          todo_result = todo_tool.execute(action: "list", todos_storage: @todos)
+          if todo_result.is_a?(Hash) && todo_result[:todos]
+            todo_result[:todos].select { |t| t[:status] == "pending" }
+          else
+            []
+          end
+        rescue
+          []
+        end
+
+        # Only inject reminder if there are pending TODOs
+        return result unless pending_todos && !pending_todos.empty?
+
+        # Create a friendly reminder message
+        reminder = "\n\n📋 REMINDER: You have #{pending_todos.length} pending TODO(s). " \
+                   "After completing each task, remember to mark it as complete using " \
+                   "todo_manager with action 'complete' and the task id."
+
+        # Inject reminder based on result type
+        case result
+        when String
+          result + reminder
+        when Hash
+          result.merge({ _todo_reminder: reminder.strip })
+        when Array
+          result + [{ _todo_reminder: reminder.strip }]
+        else
+          result
+        end
+      end
+
+      # Build feedback message from preview error
+      # @param tool_name [String] Name of the tool
+      # @param error_info [Hash] Error information from preview
+      # @return [String] Feedback message
+      private def build_preview_error_feedback(tool_name, error_info)
+        case tool_name
+        when "edit"
+          "Tool edit denied: The edit operation will fail because the old_string was not found in the file. " \
+          "Please use file_reader to read '#{error_info[:path]}' first, " \
+          "find the correct string to replace, and try again with the exact string (including whitespace)."
+        else
+          "Tool preview error: #{error_info[:error]}"
+        end
+      end
+
+      # Show preview for write tool
+      # @param args [Hash] Write tool arguments
+      # @return [nil] Always returns nil (no errors for write)
+      private def show_write_preview(args)
+        path = args[:path] || args['path']
+        # Expand ~ to home directory so File.exist? works correctly
+        expanded_path = path&.start_with?("~") ? File.expand_path(path) : path
+        new_content = args[:content] || args['content'] || ""
+
+        is_new_file = !(expanded_path && File.exist?(expanded_path))
+        @ui&.show_file_write_preview(path, is_new_file: is_new_file)
+
+        if is_new_file
+          @ui&.show_diff("", new_content, max_lines: 50)
+        else
+          old_content = File.read(expanded_path)
+          old_content = old_content.encode("UTF-8", invalid: :replace, undef: :replace, replace: "\u{FFFD}") unless old_content.encoding == Encoding::UTF_8 && old_content.valid_encoding?
+          @ui&.show_diff(old_content, new_content, max_lines: 50)
+        end
+        nil
+      end
+
+      # Show preview for edit tool
+      # @param args [Hash] Edit tool arguments
+      # @return [Hash, nil] Error information if preview detected issues
+      private def show_edit_preview(args)
+        path = args[:path] || args[:file_path] || args['path'] || args['file_path']
+        old_string = args[:old_string] || args['old_string'] || ""
+        new_string = args[:new_string] || args['new_string'] || ""
+        replace_all = args[:replace_all] || args['replace_all'] || false
+
+        # Expand ~ to home directory so File.exist? and File.read work correctly
+        expanded_path = path&.start_with?("~") ? File.expand_path(path) : path
+
+        @ui&.show_file_edit_preview(path)
+
+        if !expanded_path || expanded_path.empty?
+          @ui&.show_file_error("No file path provided")
+          return { error: "No file path provided for edit operation" }
+        end
+
+        unless File.exist?(expanded_path)
+          @ui&.show_file_error("File not found: #{path}")
+          return { error: "File not found: #{path}", path: path }
+        end
+
+        if old_string.empty?
+          @ui&.show_file_error("No old_string provided (nothing to replace)")
+          return { error: "No old_string provided (nothing to replace)" }
+        end
+
+        file_content = File.read(expanded_path)
+
+        # Use the same find_match logic as Edit tool to handle fuzzy matching
+        # (trim, unescape, smart line matching) — prevents diff from being blank
+        # when simple include? fails but Edit#execute's fuzzy match would succeed
+        match_result = Utils::StringMatcher.find_match(file_content, old_string)
+
+        unless match_result
+          # Log debug info for troubleshooting
+          @debug_logs << {
+            timestamp: Time.now.iso8601,
+            event: "edit_preview_failed",
+            path: path,
+            looking_for: old_string[0..500],
+            file_content_preview: file_content[0..1000],
+            file_size: file_content.length
+          }
+
+          @ui&.show_file_error("Edit file error")
+          return {
+            error: "String to replace not found in file",
+            path: path,
+            looking_for: old_string[0..200]
+          }
+        end
+
+        # Use the actual matched string (may differ via trim/unescape) for replacement
+        actual_old_string = match_result[:matched_string]
+
+        # Use the same replace logic as the actual tool execution
+        new_content = if replace_all
+                        file_content.gsub(actual_old_string, new_string)
+                      else
+                        file_content.sub(actual_old_string, new_string)
+                      end
+        @ui&.show_diff(file_content, new_content, max_lines: 50)
+        nil  # No error
+      end
+
+      # Show preview for shell tool
+      # @param args [Hash] Shell tool arguments
+      # @return [nil] Always returns nil
+      private def show_shell_preview(args)
+        command = args[:command] || ""
+        @ui&.show_shell_preview(command)
+        nil
+      end
+    end
+  end
+end

data/lib/octo/agent/tool_registry.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Octo
+  class ToolRegistry
+    # Common aliases that LLMs frequently use instead of the registered tool names.
+    # Keys are downcased aliases; values are the canonical registered names.
+    TOOL_ALIASES = {
+      # file_reader aliases
+      "read" => "file_reader",
+      "read_file" => "file_reader",
+      "filereader" => "file_reader",
+      "file_read" => "file_reader",
+      "cat" => "file_reader",
+      # write aliases
+      "write_file" => "write",
+      "create_file" => "write",
+      "file_write" => "write",
+      # edit aliases
+      "file_edit" => "edit",
+      "replace" => "edit",
+      "replace_in_file" => "edit",
+      "str_replace" => "edit",
+      # terminal aliases
+      "shell" => "terminal",
+      "bash" => "terminal",
+      "exec" => "terminal",
+      "execute" => "terminal",
+      "run_command" => "terminal",
+      "run" => "terminal",
+      "command" => "terminal",
+      # web_search aliases
+      "search" => "web_search",
+      "websearch" => "web_search",
+      "internet_search" => "web_search",
+      "online_search" => "web_search",
+      # web_fetch aliases
+      "fetch" => "web_fetch",
+      "webfetch" => "web_fetch",
+      "browse" => "web_fetch",
+      "url_fetch" => "web_fetch",
+      "http_get" => "web_fetch",
+      # grep aliases
+      "search_files" => "grep",
+      "search_in_files" => "grep",
+      "find_in_files" => "grep",
+      "search_code" => "grep",
+      # glob aliases
+      "find_files" => "glob",
+      "list_files" => "glob",
+      "file_glob" => "glob",
+      "search_filenames" => "glob",
+      # invoke_skill aliases
+      "skill" => "invoke_skill",
+      "run_skill" => "invoke_skill",
+      # todo_manager aliases
+      "todo" => "todo_manager",
+      "task_manager" => "todo_manager",
+      # request_user_feedback aliases
+      "ask_user" => "request_user_feedback",
+      "user_feedback" => "request_user_feedback",
+      "ask" => "request_user_feedback",
+      # undo_task aliases
+      "undo" => "undo_task",
+      # redo_task aliases
+      "redo" => "redo_task",
+      # list_tasks aliases
+      "tasks" => "list_tasks",
+      "task_history" => "list_tasks",
+      # trash_manager aliases
+      "trash" => "trash_manager",
+      "delete" => "trash_manager",
+      "rm" => "trash_manager",
+      "remove" => "trash_manager",
+    }.freeze
+
+    def initialize
+      @tools = {}
+      # Downcased index for case-insensitive lookups
+      @downcased_index = {}
+    end
+
+    def register(tool)
+      @tools[tool.name] = tool
+      @downcased_index[tool.name.downcase] = tool.name
+    end
+
+    def get(name)
+      @tools[name] || raise(Octo::ToolCallError, "Tool not found: #{name}")
+    end
+
+    # Resolve a tool name (possibly misspelt or aliased) to the canonical
+    # registered name.  Resolution order:
+    #   1. Exact match in the registry
+    #   2. Case-insensitive match (e.g. "Read" → "file_reader")
+    #   3. Alias lookup (e.g. "read_file" → "file_reader")
+    # Returns the canonical tool name, or nil if nothing matched.
+    def resolve(name)
+      return name if @tools.key?(name)
+
+      downcased = name.downcase
+
+      # Case-insensitive match
+      if @downcased_index.key?(downcased)
+        return @downcased_index[downcased]
+      end
+
+      # Alias lookup
+      if TOOL_ALIASES.key?(downcased)
+        return TOOL_ALIASES[downcased]
+      end
+
+      # Fuzzy: try underscore / hyphen normalisation (e.g. "file-reader" → "file_reader")
+      normalized = downcased.tr("-", "_")
+      if normalized != downcased
+        if @downcased_index.key?(normalized)
+          return @downcased_index[normalized]
+        end
+        if TOOL_ALIASES.key?(normalized)
+          return TOOL_ALIASES[normalized]
+        end
+      end
+
+      nil
+    end
+
+    def all
+      @tools.values
+    end
+
+    def all_definitions
+      @tools.values.map(&:to_function_definition)
+    end
+
+    def allowed_definitions(allowed_tools = nil)
+      return all_definitions if allowed_tools.nil? || allowed_tools.include?("all")
+
+      @tools.select { |name, _| allowed_tools.include?(name) }
+             .values
+             .map(&:to_function_definition)
+    end
+
+    def tool_names
+      @tools.keys
+    end
+
+    def by_category(category)
+      @tools.values.select { |tool| tool.category == category }
+    end
+  end
+end