ace-llm-providers-cli 0.27.0

data/lib/ace/llm/providers/cli/molecules/safe_capture.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        module Molecules
+          # Thread-safe command execution with process-level timeout.
+          #
+          # Replaces the unsafe Timeout.timeout { Open3.capture3(...) } pattern
+          # which causes "stream closed in another thread (IOError)" when the
+          # timeout fires while Open3's internal reader threads hold pipe handles.
+          #
+          # Uses Open3.popen3 + Process.kill so the child process is terminated
+          # directly — no thread interruption, no IOError.
+          class SafeCapture
+            # @param cmd [Array<String>] Command arguments
+            # @param timeout [Integer] Timeout in seconds
+            # @param stdin_data [String, nil] Data to write to stdin
+            # @param chdir [String, nil] Working directory
+            # @param env [Hash, nil] Environment variables (merged with current env)
+            # @param provider_name [String] Provider name for error messages
+            # @param isolate_process_group [Boolean] Spawn subprocess in isolated process group
+            # @param cleanup_group_on_exit [Boolean] Best-effort cleanup of descendants on success
+            # @return [Array(String, String, Process::Status)] [stdout, stderr, status]
+            # @raise [Ace::LLM::ProviderError] on timeout
+            def self.call(cmd, timeout:, stdin_data: nil, chdir: nil, env: nil, provider_name: "CLI",
+              isolate_process_group: true, cleanup_group_on_exit: true)
+              normalized_timeout = normalize_timeout(timeout)
+              opts = {}
+              opts[:chdir] = chdir if chdir
+              opts[:pgroup] = true if isolate_process_group
+
+              args = env ? [env, *cmd] : cmd
+
+              Open3.popen3(*args, **opts) do |stdin, stdout, stderr, wait_thr|
+                pid = wait_thr.pid
+                pgid = safe_getpgid(pid)
+                debug_log(provider_name, "spawn pid=#{pid} pgid=#{pgid || "n/a"}")
+
+                begin
+                  stdin.write(stdin_data) if stdin_data
+                rescue Errno::EPIPE
+                  # Subprocess exited before consuming stdin — continue to capture stderr for the real error
+                end
+                stdin.close
+
+                out_reader = Thread.new { safe_read_stream(stdout) }
+                err_reader = Thread.new { safe_read_stream(stderr) }
+                out_reader.report_on_exception = false
+                err_reader.report_on_exception = false
+
+                unless wait_thr.join(normalized_timeout)
+                  # Timeout: kill subprocess group (and descendants), then clean up
+                  terminate_subprocess_tree(pid: pid, pgid: pgid, provider_name: provider_name)
+                  wait_thr.join(5)
+
+                  stdout.close unless stdout.closed?
+                  stderr.close unless stderr.closed?
+                  out_reader.join(1)
+                  err_reader.join(1)
+                  out_reader.kill if out_reader.alive?
+                  err_reader.kill if err_reader.alive?
+                  raise Ace::LLM::ProviderError,
+                    "#{provider_name} CLI execution timed out after #{normalized_timeout} seconds"
+                end
+
+                status = wait_thr.value
+                if isolate_process_group && cleanup_group_on_exit
+                  terminate_descendants_after_success(pid: pid, pgid: pgid, provider_name: provider_name)
+                end
+
+                [out_reader.value, err_reader.value, status]
+              end
+            end
+
+            class << self
+              private
+
+              def safe_read_stream(io)
+                io.read
+              rescue IOError
+                ""
+              end
+
+              def normalize_timeout(value)
+                return value if value.is_a?(Numeric) && value.finite?
+
+                normalized = value.to_s.strip
+                normalized_timeout = Float(normalized)
+                raise ArgumentError, "timeout must be positive" unless normalized_timeout.positive?
+
+                normalized_timeout
+              rescue ArgumentError, TypeError
+                raise ArgumentError, "timeout must be a positive numeric value, got #{value.inspect}"
+              end
+
+              def terminate_subprocess_tree(pid:, pgid:, provider_name:)
+                debug_log(provider_name, "timeout cleanup pid=#{pid} pgid=#{pgid || "n/a"}")
+                terminate_group_or_pid("TERM", pid, pgid)
+                sleep(0.1)
+                terminate_group_or_pid("KILL", pid, pgid)
+              end
+
+              def terminate_descendants_after_success(pid:, pgid:, provider_name:)
+                return unless pgid
+                return unless group_alive?(pgid)
+
+                debug_log(provider_name, "post-exit cleanup pgid=#{pgid}")
+                terminate_group_or_pid("TERM", pid, pgid)
+                sleep(0.05)
+                terminate_group_or_pid("KILL", pid, pgid) if group_alive?(pgid)
+              end
+
+              def terminate_group_or_pid(signal, pid, pgid)
+                if pgid
+                  Process.kill(signal, -pgid)
+                else
+                  Process.kill(signal, pid)
+                end
+              rescue Errno::ESRCH, Errno::EPERM
+                nil
+              end
+
+              def safe_getpgid(pid)
+                Process.getpgid(pid)
+              rescue Errno::ESRCH
+                nil
+              end
+
+              def group_alive?(pgid)
+                Process.kill(0, -pgid)
+                true
+              rescue Errno::ESRCH
+                false
+              rescue Errno::EPERM
+                true
+              end
+
+              def debug_log(provider_name, message)
+                return unless ENV["ACE_LLM_DEBUG_SUBPROCESS"] == "1"
+
+                warn("[SafeCapture][#{provider_name}] #{message}")
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/molecules/session_finder.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "../atoms/session_finders/claude_session_finder"
+require_relative "../atoms/session_finders/codex_session_finder"
+require_relative "../atoms/session_finders/pi_session_finder"
+require_relative "../atoms/session_finders/gemini_session_finder"
+require_relative "../atoms/session_finders/open_code_session_finder"
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        module Molecules
+          # Dispatches session detection to the appropriate provider-specific finder.
+          #
+          # Used as a fallback when a provider doesn't natively return a session_id.
+          # Each finder scans the provider's local session storage and matches by prompt.
+          class SessionFinder
+            FINDERS = {
+              "claude" => Atoms::SessionFinders::ClaudeSessionFinder,
+              "codex" => Atoms::SessionFinders::CodexSessionFinder,
+              "pi" => Atoms::SessionFinders::PiSessionFinder,
+              "gemini" => Atoms::SessionFinders::GeminiSessionFinder,
+              "opencode" => Atoms::SessionFinders::OpenCodeSessionFinder
+            }.freeze
+
+            # @param provider [String] provider name
+            # @param working_dir [String] project directory
+            # @param prompt [String] the prompt sent to the provider
+            # @return [Hash, nil] { session_id:, session_path: } or nil
+            def self.call(provider:, working_dir:, prompt:)
+              finder = FINDERS[provider]
+              return nil unless finder
+
+              finder.call(working_dir: working_dir, prompt: prompt)
+            rescue
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/molecules/skill_name_reader.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "date"
+require "yaml"
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        module Molecules
+          # Reads skill names from SKILL.md frontmatter in a skills directory.
+          #
+          # Scans `#{skills_dir}/*/SKILL.md` for YAML frontmatter with a `name:` field.
+          # Results are cached per directory path since skills don't change during a session.
+          class SkillNameReader
+            def initialize
+              @cache = {}
+            end
+
+            # Read skill names from a skills directory.
+            #
+            # @param skills_dir [String] Path to the skills directory
+            # @return [Array<String>] Array of skill names (e.g. ["ace-onboard", "ace-git-commit"])
+            def call(skills_dir)
+              return [] unless skills_dir && Dir.exist?(skills_dir)
+
+              @cache[skills_dir] ||= read_skill_names(skills_dir)
+            end
+
+            private
+
+            def read_skill_names(skills_dir)
+              skill_files = Dir.glob(File.join(skills_dir, "*", "SKILL.md"))
+              names = []
+
+              skill_files.each do |path|
+                name = extract_skill_name(path)
+                names << name if name
+              end
+
+              names.sort
+            end
+
+            def extract_skill_name(path)
+              content = File.read(path, encoding: "utf-8")
+
+              # Parse YAML frontmatter (between --- delimiters)
+              return nil unless content.start_with?("---")
+
+              end_index = content.index("---", 3)
+              return nil unless end_index
+
+              frontmatter = content[3...end_index].strip
+              data = YAML.safe_load(frontmatter, permitted_classes: [Date])
+              data["name"] if data.is_a?(Hash)
+            rescue Errno::ENOENT, Psych::SyntaxError
+              nil
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/providers/cli/open_code_client.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "shellwords"
+
+require_relative "cli_args_support"
+require_relative "atoms/execution_context"
+
+module Ace
+  module LLM
+    module Providers
+      module CLI
+        # Client for interacting with OpenCode CLI
+        # Provides access to multiple AI providers through OpenCode's unified platform
+        class OpenCodeClient < Ace::LLM::Organisms::BaseClient
+          include CliArgsSupport
+
+          # Not used for CLI interaction but required by BaseClient
+          API_BASE_URL = "https://models.dev"
+          DEFAULT_GENERATION_CONFIG = {}.freeze
+
+          # Provider registration - auto-registers as "opencode"
+          def self.provider_name
+            "opencode"
+          end
+
+          # Default model (can be overridden by config)
+          DEFAULT_MODEL = "google/gemini-2.5-flash"
+
+          def initialize(model: nil, **options)
+            @model = model || DEFAULT_MODEL
+            # Skip normal BaseClient initialization that requires API key
+            @options = options
+            @generation_config = options[:generation_config] || {}
+          end
+
+          # Override to indicate this client doesn't need API credentials
+          def needs_credentials?
+            false
+          end
+
+          # Generate a response from the LLM
+          # @param messages [Array<Hash>] Conversation messages
+          # @param options [Hash] Generation options
+          # @return [Hash] Response with text and metadata
+          def generate(messages, **options)
+            validate_opencode_availability!
+
+            # Convert messages to prompt format
+            prompt = format_messages_as_prompt(messages)
+
+            # Build full prompt with system instruction for accurate token accounting
+            full_prompt = build_full_prompt(prompt, options)
+
+            cmd = build_opencode_command_with_prompt(full_prompt, options)
+            stdout, stderr, status = execute_opencode_command(cmd, options: options)
+
+            parse_opencode_response(stdout, stderr, status, full_prompt, options)
+          rescue => e
+            handle_opencode_error(e)
+          end
+
+          # List available OpenCode models
+          def list_models
+            # Return a standard set of models that OpenCode typically supports
+            # Actual models come from YAML config
+            [
+              {id: "google/gemini-2.5-flash", name: "Gemini 2.5 Flash", description: "Fast Google model", context_size: 1_000_000},
+              {id: "google/gemini-2.0-flash-experimental", name: "Gemini 2.0 Flash", description: "Experimental Google model", context_size: 1_000_000},
+              {id: "google/gemini-1.5-pro", name: "Gemini 1.5 Pro", description: "Advanced Google model", context_size: 2_000_000},
+              {id: "anthropic/claude-3-5-sonnet", name: "Claude 3.5 Sonnet", description: "Anthropic model", context_size: 200_000},
+              {id: "anthropic/claude-3-5-haiku", name: "Claude 3.5 Haiku", description: "Fast Anthropic model", context_size: 200_000},
+              {id: "openai/gpt-4o", name: "GPT-4 Omni", description: "OpenAI model", context_size: 128_000},
+              {id: "openai/gpt-4o-mini", name: "GPT-4 Omni Mini", description: "Small OpenAI model", context_size: 128_000}
+            ]
+          end
+
+          private
+
+          def format_messages_as_prompt(messages)
+            # Handle both array of message hashes and string prompt
+            return messages if messages.is_a?(String)
+
+            # Convert array of messages to formatted prompt
+            formatted = messages.map do |msg|
+              role = msg[:role] || msg["role"]
+              content = msg[:content] || msg["content"]
+
+              case role
+              when "system"
+                "System: #{content}"
+              when "user"
+                "User: #{content}"
+              when "assistant"
+                "Assistant: #{content}"
+              else
+                content
+              end
+            end
+
+            formatted.join("\n\n")
+          end
+
+          def opencode_available?
+            system("which opencode > /dev/null 2>&1")
+          end
+
+          def validate_opencode_availability!
+            unless opencode_available?
+              raise Ace::LLM::ProviderError, "OpenCode CLI not found. Install with: npm install -g opencode-cli or visit https://opencode.dev"
+            end
+
+            # Check if OpenCode is authenticated (quick check)
+            unless opencode_authenticated?
+              raise Ace::LLM::AuthenticationError, "OpenCode authentication required. Run 'opencode auth' to configure"
+            end
+          end
+
+          def opencode_authenticated?
+            # Quick check if OpenCode can execute (will fail fast if not authenticated)
+
+            cmd = ["opencode", "--version"]
+            _, _, status = Open3.capture3(*cmd)
+            status.success?
+          rescue
+            false
+          end
+
+          # Build command array with pre-built full prompt
+          # @param full_prompt [String] The complete prompt (already includes system instruction if any)
+          # @param options [Hash] Generation options (unused for command flags, kept for API compatibility)
+          # @return [Array<String>] Command array ready for execution
+          def build_opencode_command_with_prompt(full_prompt, options)
+            cmd = ["opencode", "run"]
+
+            # Add model selection with fallback chain
+            model_to_use = @model || @generation_config[:model] || DEFAULT_MODEL
+            cmd << "--model" << model_to_use
+
+            # Add JSON format for structured output (less likely to prompt interactively)
+            cmd << "--format" << "json"
+
+            # User CLI args after generated flags so they take precedence (last-wins),
+            # but before positional prompt arg
+            cmd.concat(normalized_cli_args(options))
+
+            # Prompt is passed as positional argument (not via --prompt flag)
+            # NOTE: OpenCode CLI does not support --temperature, --max-tokens, or --system flags
+            # Coerce to string to handle nil or non-string inputs gracefully
+            cmd << full_prompt.to_s
+
+            cmd
+          end
+
+          # Legacy method for backward compatibility and tests
+          # @deprecated Use build_full_prompt + build_opencode_command_with_prompt instead
+          def build_opencode_command(prompt, options)
+            full_prompt = build_full_prompt(prompt, options)
+            build_opencode_command_with_prompt(full_prompt, options)
+          end
+
+          # Build full prompt by prepending system instruction if provided
+          #
+          # OpenCode CLI does not support a --system flag, so we prepend system
+          # instructions to the main prompt using the "System: " prefix format.
+          #
+          # @param prompt [String] The main user prompt (may already contain "System:" from message formatting)
+          # @param options [Hash] Options that may contain system instruction keys
+          # @return [String] Full prompt with system instruction prepended if provided
+          # @note System instruction priority order (first match wins):
+          #   1. options[:system_instruction]
+          #   2. options[:system]
+          #   3. options[:system_prompt]
+          #   4. @generation_config[:system_prompt]
+          # @note If the prompt already starts with "System:" (from format_messages_as_prompt),
+          #   the options-based system instruction is skipped to avoid duplication.
+          def build_full_prompt(prompt, options)
+            prompt_str = prompt.to_s
+
+            # Skip prepending if prompt already has a system instruction from message formatting
+            # This prevents double "System:" prefixes when messages contain role: "system"
+            return prompt_str if prompt_str.start_with?("System:")
+
+            system_content = options[:system_instruction] ||
+              options[:system] ||
+              options[:system_prompt] ||
+              @generation_config[:system_prompt]
+
+            if system_content
+              "System: #{system_content}\n\n#{prompt_str}"
+            else
+              prompt_str
+            end
+          end
+
+          def execute_opencode_command(cmd, timeout: nil, options: {})
+            timeout_val = timeout || @options[:timeout] || 120
+            working_dir = Atoms::ExecutionContext.resolve_working_dir(
+              working_dir: options[:working_dir],
+              subprocess_env: options[:subprocess_env]
+            )
+            Molecules::SafeCapture.call(
+              cmd,
+              timeout: timeout_val,
+              stdin_data: "",
+              chdir: working_dir,
+              provider_name: "OpenCode"
+            )
+          end
+
+          def parse_opencode_response(stdout, stderr, status, prompt, options)
+            unless status.success?
+              error_msg = stderr.empty? ? stdout : stderr
+
+              # Detect common error patterns for better error messages
+              if error_msg.include?("400") || error_msg.include?("Bad Request")
+                raise Ace::LLM::ProviderError, "OpenCode API request failed (400 Bad Request). The model or prompt may be invalid."
+              end
+
+              raise Ace::LLM::ProviderError, "OpenCode CLI failed: #{error_msg}"
+            end
+
+            begin
+              # Try to parse as JSON first
+              response = JSON.parse(stdout)
+              text = response["result"] || response["text"] || response["response"] || ""
+            rescue JSON::ParserError
+              # Fall back to treating entire output as text
+              text = stdout.strip
+              response = {}
+            end
+
+            # Build metadata
+            metadata = build_metadata(response, text, prompt, options)
+
+            # Return hash compatible with ace-llm format
+            {
+              text: text,
+              metadata: metadata
+            }
+          end
+
+          def build_metadata(response, text, prompt, options)
+            # Build standard metadata structure
+            usage = response["usage"] || {}
+
+            # Rough token estimation if not provided
+            prompt_tokens = usage["input_tokens"] || (prompt.to_s.length / 4).round
+            output_tokens = usage["output_tokens"] || (text.length / 4).round
+
+            {
+              provider: "opencode",
+              model: @model || DEFAULT_MODEL,
+              input_tokens: prompt_tokens,
+              output_tokens: output_tokens,
+              total_tokens: prompt_tokens + output_tokens,
+              finish_reason: response["finish_reason"] || "success",
+              timestamp: Time.now.utc.iso8601
+            }
+          end
+
+          def handle_opencode_error(error)
+            # Re-raise the error for proper handling by the base client error flow
+            raise error
+          end
+        end
+      end
+    end
+  end
+end