agent-cli-runtime 0.1.0 → 0.2.0

data/lib/agent_cli_runtime/profile.rb

@@ -25,7 +25,10 @@ module AgentCliRuntime
                 :budget_flag, :output_format_flags, :version_flag,
                 :min_version, :prompt_style, :model_argument_builder,
                 :effort_argument_builder, :launcher_identity,
-                :cli_capabilities, :declared_capability_support
+                :cli_capabilities, :declared_capability_support,
+                :credential_environment_keys, :configuration_environment_key,
+                :default_configuration_directory,
+                :permission_policy_required, :result_parser
 
     def initialize(name:, bin_default:, headless_flag:, version_flag:,
                    env_bin_override_keys: [], permission_skip_flag: nil,
@@ -35,7 +38,10 @@ module AgentCliRuntime
                    prompt_style: :positional, model_argument_builder: nil,
                    effort_argument_builder: nil, launcher_identity: nil,
                    usage_extractor: nil, auth_configuration_probe: nil,
-                   cli_capabilities: {}, raw_cli_arguments_supported: false)
+                   cli_capabilities: {}, raw_cli_arguments_supported: false,
+                   credential_environment_keys: [], configuration_environment_key: nil,
+                   default_configuration_directory: nil,
+                   permission_policy_required: false, result_parser: nil)
       normalized_prompt_style = prompt_style.to_sym
       unless PROMPT_STYLES.include?(normalized_prompt_style)
         raise ArgumentError,
@@ -65,6 +71,17 @@ module AgentCliRuntime
       @auth_configuration_probe = auth_configuration_probe
       @cli_capabilities = normalize_cli_capabilities(cli_capabilities)
       @raw_cli_arguments_supported = raw_cli_arguments_supported == true
+      @credential_environment_keys = immutable_environment_keys(
+        credential_environment_keys
+      )
+      @configuration_environment_key = optional_environment_key(
+        configuration_environment_key
+      )
+      @default_configuration_directory = optional_relative_directory(
+        default_configuration_directory
+      )
+      @permission_policy_required = permission_policy_required == true
+      @result_parser = result_parser
       @declared_capability_support = build_declared_capability_support
       freeze
     end
@@ -89,6 +106,10 @@ module AgentCliRuntime
         raise ArgumentError,
               "agent profile #{@name.inspect} cannot enforce read-only sandboxing"
       end
+      if permission_mode.nil? && @permission_policy_required
+        raise ConfigurationError,
+              "agent profile #{@name.inspect} requires an explicit OpenCode permission policy"
+      end
       return [] unless @permission_skip_flag
       return [ @permission_skip_flag ] unless @name == :claude && permission_mode
       return [ @permission_skip_flag ] if permission_mode == "bypassPermissions"
@@ -200,6 +221,44 @@ module AgentCliRuntime
       nil
     end
 
+    def parse_run(stdout)
+      unless @result_parser
+        raise UnsupportedCapability,
+              "agent profile #{@name.inspect} has no strict result parser"
+      end
+
+      @result_parser.parse_run(stdout)
+    end
+
+    def normalize_captured_result(captured, requested_route:)
+      unless @result_parser
+        raise UnsupportedCapability,
+              "agent profile #{@name.inspect} has no strict result parser"
+      end
+
+      @result_parser.normalize(
+        captured, requested_route: requested_route, profile: self
+      )
+    end
+
+    def configuration_directory(home: nil, env: ENV)
+      if @configuration_environment_key
+        configured = env[@configuration_environment_key].to_s
+        unless configured.empty?
+          unless File.absolute_path?(configured)
+            raise ArgumentError,
+                  "#{@configuration_environment_key} must be an absolute directory"
+          end
+          return File.expand_path(configured)
+        end
+      end
+      return nil unless @default_configuration_directory
+
+      base = home || env["HOME"]
+      base = Dir.home if base.to_s.empty?
+      File.expand_path(@default_configuration_directory, base)
+    end
+
     def require_cli_capability!(capability)
       capability_name = capability.to_sym
       flags = @cli_capabilities[capability_name]
@@ -219,6 +278,12 @@ module AgentCliRuntime
       flags.dup
     end
 
+    def capture_local(*arguments, env: ENV, timeout_sec: CAPTURE_TIMEOUT_SECONDS)
+      bounded_capture3(
+        bin(env:), *arguments, timeout_sec: timeout_sec, env: env
+      )
+    end
+
     private
 
     def immutable_string(value)
@@ -229,6 +294,35 @@ module AgentCliRuntime
       Array(values).map { |value| immutable_string(value) }.freeze
     end
 
+    def immutable_environment_keys(values)
+      keys = immutable_strings(values)
+      invalid = keys.find { |key| !key.match?(/\A[A-Z][A-Z0-9_]*\z/) }
+      raise ArgumentError, "invalid credential environment key #{invalid.inspect}" if invalid
+      raise ArgumentError, "credential environment keys must be unique" if keys.uniq.length != keys.length
+
+      keys
+    end
+
+    def optional_environment_key(value)
+      return nil if value.nil?
+
+      key = immutable_string(value)
+      unless key.match?(/\A[A-Z][A-Z0-9_]*\z/)
+        raise ArgumentError, "invalid configuration environment key #{key.inspect}"
+      end
+      key
+    end
+
+    def optional_relative_directory(value)
+      return nil if value.nil?
+
+      path = immutable_string(value)
+      if path.empty? || File.absolute_path?(path)
+        raise ArgumentError, "default configuration directory must be relative"
+      end
+      path
+    end
+
     def normalize_tool_scope_flags(flags)
       unless flags.is_a?(Hash)
         raise ArgumentError, "tool_scope_flags must be a Hash"

data/lib/agent_cli_runtime/profiles.rb

@@ -1,5 +1,52 @@
 module AgentCliRuntime
   module Profiles
+    PI_CREDENTIAL_ENVIRONMENT_KEYS = %w[
+      AI_GATEWAY_API_KEY
+      ANTHROPIC_API_KEY
+      ANTHROPIC_AUTH_TOKEN
+      ANTHROPIC_OAUTH_TOKEN
+      ANT_LING_API_KEY
+      AWS_ACCESS_KEY_ID
+      AWS_BEARER_TOKEN_BEDROCK
+      AWS_CONTAINER_CREDENTIALS_FULL_URI
+      AWS_CONTAINER_CREDENTIALS_RELATIVE_URI
+      AWS_PROFILE
+      AWS_SECRET_ACCESS_KEY
+      AWS_SESSION_TOKEN
+      AWS_WEB_IDENTITY_TOKEN_FILE
+      AZURE_OPENAI_API_KEY
+      BASETEN_API_KEY
+      CEREBRAS_API_KEY
+      CLOUDFLARE_API_KEY
+      COPILOT_GITHUB_TOKEN
+      DEEPSEEK_API_KEY
+      FIREWORKS_API_KEY
+      GEMINI_API_KEY
+      GOOGLE_APPLICATION_CREDENTIALS
+      GOOGLE_CLOUD_API_KEY
+      GROQ_API_KEY
+      HF_TOKEN
+      KIMI_API_KEY
+      MINIMAX_API_KEY
+      MINIMAX_CN_API_KEY
+      MISTRAL_API_KEY
+      MOONSHOT_API_KEY
+      NVIDIA_API_KEY
+      OPENCODE_API_KEY
+      OPENAI_API_KEY
+      OPENROUTER_API_KEY
+      QWEN_TOKEN_PLAN_API_KEY
+      RADIUS_API_KEY
+      TOGETHER_API_KEY
+      XAI_API_KEY
+      XIAOMI_API_KEY
+      XIAOMI_TOKEN_PLAN_AMS_API_KEY
+      XIAOMI_TOKEN_PLAN_CN_API_KEY
+      XIAOMI_TOKEN_PLAN_SGP_API_KEY
+      ZAI_API_KEY
+      ZAI_CODING_CN_API_KEY
+    ].freeze
+
     module_function
 
     def names
@@ -56,6 +103,37 @@ module AgentCliRuntime
       home_path(home, ".grok", "auth.json")
     end
 
+    def opencode_auth_path(home:, env:)
+      data_home = env["XDG_DATA_HOME"]
+      if !data_home.to_s.empty?
+        unless File.absolute_path?(data_home)
+          raise ArgumentError, "XDG_DATA_HOME must be absolute"
+        end
+
+        return File.join(data_home, "opencode", "auth.json")
+      end
+
+      home_path(home, ".local", "share", "opencode", "auth.json")
+    end
+
+    def opencode_model_arguments(model)
+      route = Route.parse(model)
+      [ "--model", route.to_s ]
+    end
+
+    OPENCODE_VARIANTS = %w[minimal low medium high xhigh max].freeze
+
+    def opencode_variant_arguments(variant)
+      normalized = variant.to_s
+      unless OPENCODE_VARIANTS.include?(normalized)
+        raise ArgumentError,
+              "unsupported OpenCode variant #{variant.inspect}; expected one of " \
+              "#{OPENCODE_VARIANTS.join(', ')}"
+      end
+
+      [ "--variant", normalized ]
+    end
+
     CLAUDE = Profile.new(
       name: :claude,
       bin_default: "claude",
@@ -78,6 +156,11 @@ module AgentCliRuntime
       effort_argument_builder: ->(effort) { [ "--effort", effort ] },
       launcher_identity: "claude-code/v1",
       usage_extractor: UsageExtractors::CLAUDE,
+      credential_environment_keys: %w[
+        ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN CLAUDE_API_KEY
+      ],
+      configuration_environment_key: "CLAUDE_CONFIG_DIR",
+      default_configuration_directory: ".claude",
       raw_cli_arguments_supported: true,
       auth_configuration_probe: lambda do |home:, env:|
         if env_configured?(env, "ANTHROPIC_API_KEY")
@@ -117,6 +200,9 @@ module AgentCliRuntime
         ->(effort) { [ "-c", "model_reasoning_effort=#{effort}" ] },
       launcher_identity: "codex-cli/v1",
       usage_extractor: UsageExtractors::CODEX,
+      credential_environment_keys: %w[OPENAI_API_KEY],
+      configuration_environment_key: "CODEX_HOME",
+      default_configuration_directory: ".codex",
       auth_configuration_probe: lambda do |home:, env:|
         if env_configured?(env, "OPENAI_API_KEY")
           AuthConfiguration.new(status: :configured, source: "environment")
@@ -140,6 +226,9 @@ module AgentCliRuntime
       model_argument_builder: ->(model) { [ "--model", model ] },
       launcher_identity: "pi-coding-agent/v1",
       usage_extractor: UsageExtractors::PI,
+      credential_environment_keys: PI_CREDENTIAL_ENVIRONMENT_KEYS,
+      configuration_environment_key: "PI_CODING_AGENT_DIR",
+      default_configuration_directory: ".pi/agent",
       auth_configuration_probe: lambda do |home:, env:|
         directory = env["PI_CODING_AGENT_DIR"]
         path =
@@ -169,6 +258,9 @@ module AgentCliRuntime
         ->(effort) { [ "--reasoning-effort", effort ] },
       launcher_identity: "grok-cli/v1",
       usage_extractor: UsageExtractors::GROK,
+      credential_environment_keys: %w[GROK_AUTH_PATH XAI_API_KEY GROK_CODE_XAI_API_KEY],
+      configuration_environment_key: "GROK_HOME",
+      default_configuration_directory: ".grok",
       auth_configuration_probe: lambda do |home:, env:|
         if env_configured?(env, "XAI_API_KEY", "GROK_CODE_XAI_API_KEY")
           AuthConfiguration.new(status: :configured, source: "environment")
@@ -181,7 +273,45 @@ module AgentCliRuntime
       end
     )
 
-    PROFILES = [ CLAUDE, CODEX, PI, GROK ].to_h do |profile|
+    OPENCODE = Profile.new(
+      name: :opencode,
+      bin_default: "opencode",
+      env_bin_override_keys: %w[
+        AGENT_CLI_RUNTIME_OPENCODE_BIN HIVE_OPENCODE_BIN
+      ],
+      headless_flag: "run",
+      output_format_flags: [ "--format", "json" ],
+      version_flag: "--version",
+      min_version: "1.18.16",
+      model_argument_builder: ->(model) { opencode_model_arguments(model) },
+      effort_argument_builder:
+        ->(variant) { opencode_variant_arguments(variant) },
+      launcher_identity: "opencode-cli/v1",
+      credential_environment_keys: PI_CREDENTIAL_ENVIRONMENT_KEYS,
+      configuration_environment_key: "OPENCODE_CONFIG_DIR",
+      default_configuration_directory: ".config/opencode",
+      permission_policy_required: true,
+      result_parser: OpenCode::ResultParser,
+      cli_capabilities: {
+        json_events: [ "run", "--format" ],
+        working_directory: [ "run", "--dir" ],
+        model_variant: [ "run", "--variant" ],
+        pure: [ "run", "--pure" ],
+        sanitized_export: [ "export", "--sanitize" ]
+      },
+      auth_configuration_probe: lambda do |home:, env:|
+        if env_configured?(env, *PI_CREDENTIAL_ENVIRONMENT_KEYS)
+          AuthConfiguration.new(status: :configured, source: "environment")
+        else
+          auth_from_file(
+            opencode_auth_path(home:, env:),
+            source: "opencode auth.json"
+          )
+        end
+      end
+    )
+
+    PROFILES = [ CLAUDE, CODEX, PI, GROK, OPENCODE ].to_h do |profile|
       [ profile.name, profile ]
     end.freeze
     PROVIDER_ORDER = PROFILES.keys.freeze

data/lib/agent_cli_runtime/runtime.rb

@@ -63,9 +63,13 @@ module AgentCliRuntime
       compilation_error!(profile, e)
     end
 
-    def prepare!(profile)
+    def prepare!(profile, env: ENV)
+      if profile.is_a?(OpenCodePreparationRequest)
+        return OpenCode::Overlay.prepare!(profile, env:)
+      end
+
       resolved = Profiles.resolve(profile)
-      result = Probe.call(resolved)
+      result = Probe.call(resolved, env:)
       return result if result.ready
 
       evidence = unsupported_evidence(
@@ -116,7 +120,18 @@ module AgentCliRuntime
         final_message: raw[:final_message],
         diagnostic: Redactor.diagnostic(
           raw[:error_message] || raw[:limit_text]
-        )
+        ),
+        provider_signal: raw[:provider_signal]
+      )
+    end
+
+    def parse_run(profile, stdout:)
+      Profiles.resolve(profile).parse_run(stdout)
+    end
+
+    def normalize(profile, captured, requested_route:)
+      Profiles.resolve(profile).normalize_captured_result(
+        captured, requested_route:
       )
     end