agent-cli-runtime 0.1.1 → 0.2.4

data/lib/agent_cli_runtime/values.rb

@@ -1,4 +1,11 @@
 module AgentCliRuntime
+  OPENCODE_OVERLAY_ENVIRONMENT_KEYS = %w[
+    XDG_CONFIG_HOME XDG_DATA_HOME XDG_CACHE_HOME XDG_STATE_HOME TMPDIR
+    OPENCODE_CONFIG OPENCODE_DISABLE_PROJECT_CONFIG
+    OPENCODE_DISABLE_CLAUDE_CODE OPENCODE_DISABLE_MODELS_FETCH
+    OPENCODE_DISABLE_AUTOUPDATE OPENCODE_PURE
+  ].freeze
+
   module Immutable
     module_function
 
@@ -14,6 +21,28 @@ module AgentCliRuntime
     def symbols(values)
       Array(values).map(&:to_sym).uniq.freeze
     end
+
+    def hash(value)
+      unless value.is_a?(Hash)
+        raise ArgumentError, "value must be a Hash"
+      end
+
+      value.each_with_object({}) do |(key, item), result|
+        result[string(key)] = deep(item)
+      end.freeze
+    end
+
+    def deep(value)
+      case value
+      when Hash then hash(value)
+      when Array then value.map { |item| deep(item) }.freeze
+      when String then string(value)
+      when Symbol, Numeric, TrueClass, FalseClass, NilClass then value
+      else
+        raise ArgumentError,
+              "unsupported immutable value #{value.class}"
+      end
+    end
   end
   private_constant :Immutable
 
@@ -52,6 +81,12 @@ module AgentCliRuntime
     end
   end
 
+  ExtractedFailure = Data.define(:kind, :message) do
+    def initialize(kind:, message:)
+      super(kind: kind.to_sym, message: Immutable.string(message))
+    end
+  end
+
   Request = Data.define(
     :profile, :prompt, :permission_mode, :permission_arguments,
     :add_dirs, :require_add_dirs,
@@ -173,4 +208,447 @@ module AgentCliRuntime
       )
     end
   end
+
+
+  Route = Data.define(:provider, :model) do
+    ROUTE_PATTERN = /\A(?<provider>[a-zA-Z0-9][a-zA-Z0-9._-]*)\/(?<model>[^\s\/][^\s]*)\z/
+
+    def initialize(provider:, model:)
+      normalized_provider = Immutable.string(provider)
+      normalized_model = Immutable.string(model)
+      route = "#{normalized_provider}/#{normalized_model}"
+      unless ROUTE_PATTERN.match?(route) && !normalized_model.include?("\0")
+        raise ArgumentError,
+              "OpenCode route must be a full provider/model value"
+      end
+
+      super(provider: normalized_provider, model: normalized_model)
+    end
+
+    def self.parse(value)
+      match = ROUTE_PATTERN.match(value.to_s)
+      unless match
+        raise ArgumentError,
+              "OpenCode route must be a full provider/model value"
+      end
+
+      new(provider: match[:provider], model: match[:model])
+    end
+
+    def to_s
+      "#{provider}/#{model}"
+    end
+  end
+
+  OpenCodePermissionPolicy = Data.define(:rules) do
+    ACTIONS = %w[allow ask deny].freeze
+
+    def initialize(rules = nil, **keywords)
+      value = rules || keywords[:rules] || keywords
+      normalized = Immutable.hash(value || {})
+      raise ArgumentError, "OpenCode permission policy cannot be empty" if normalized.empty?
+
+      validate_actions!(normalized)
+      super(rules: normalized)
+    end
+
+    private
+
+    def validate_actions!(value)
+      value.each_value do |entry|
+        if entry.is_a?(Hash)
+          validate_actions!(entry)
+        elsif !ACTIONS.include?(entry)
+          raise ArgumentError,
+                "OpenCode permission action must be allow, ask, or deny"
+        end
+      end
+    end
+  end
+
+  OpenCodePreparationRequest = Data.define(
+    :request, :working_directory, :invocation_root,
+    :configuration_path, :configuration,
+    :credential_environment_keys, :credential_file,
+    :permission_policy, :additional_read_roots,
+    :additional_write_roots, :edit_patterns, :bash_patterns, :plugins, :pure
+  ) do
+    def initialize(request:, working_directory:, invocation_root:,
+                   configuration_path: nil, configuration: nil,
+                   credential_environment_keys: [], credential_file: nil,
+                   permission_policy: nil, additional_read_roots: [],
+                   additional_write_roots: [], edit_patterns: [],
+                   bash_patterns: [], plugins: [], pure: true)
+      unless request.is_a?(Request)
+        raise ArgumentError, "request must be an AgentCliRuntime::Request"
+      end
+      if configuration_path && configuration
+        raise ArgumentError,
+              "choose configuration_path or configuration, not both"
+      end
+      if permission_policy &&
+         !permission_policy.is_a?(OpenCodePermissionPolicy)
+        raise ArgumentError,
+              "permission_policy must be an OpenCodePermissionPolicy"
+      end
+
+      keys = Immutable.strings(credential_environment_keys)
+      invalid = keys.find { |key| !key.match?(/\A[A-Z][A-Z0-9_]*\z/) }
+      raise ArgumentError, "invalid credential environment key" if invalid
+      raise ArgumentError, "credential environment keys must be unique" if keys.uniq.length != keys.length
+      reserved = keys & OPENCODE_OVERLAY_ENVIRONMENT_KEYS
+      unless reserved.empty?
+        raise ArgumentError,
+              "credential environment keys cannot override the OpenCode overlay: #{reserved.join(', ')}"
+      end
+      normalized_bash_patterns = Immutable.strings(bash_patterns)
+      if normalized_bash_patterns.any?(&:empty?)
+        raise ArgumentError, "OpenCode bash patterns must be non-empty"
+      end
+
+      super(
+        request: request,
+        working_directory: Immutable.string(working_directory),
+        invocation_root: Immutable.string(invocation_root),
+        configuration_path:
+          configuration_path.nil? ? nil : Immutable.string(configuration_path),
+        configuration:
+          configuration.nil? ? nil : Immutable.hash(configuration),
+        credential_environment_keys: keys,
+        credential_file:
+          credential_file.nil? ? nil : Immutable.string(credential_file),
+        permission_policy: permission_policy,
+        additional_read_roots: Immutable.strings(additional_read_roots),
+        additional_write_roots: Immutable.strings(additional_write_roots),
+        edit_patterns: Immutable.strings(edit_patterns),
+        bash_patterns: normalized_bash_patterns,
+        plugins: Immutable.strings(plugins),
+        pure: pure != false
+      )
+    end
+  end
+
+  ProbeRequest = Data.define(
+    :profile, :route, :variant, :environment,
+    :credential_environment_keys, :credential_file_staged,
+    :configured_variants, :executable
+  ) do
+    def initialize(profile:, route:, variant: nil, environment: {},
+                   credential_environment_keys: [],
+                   credential_file_staged: false,
+                   configured_variants: nil,
+                   executable: nil)
+      parsed_route = route.is_a?(Route) ? route : Route.parse(route)
+      super(
+        profile: profile,
+        route: parsed_route,
+        variant: variant.nil? ? nil : Immutable.string(variant),
+        environment: Immutable.hash(environment),
+        credential_environment_keys:
+          Immutable.strings(credential_environment_keys),
+        credential_file_staged: credential_file_staged == true,
+        configured_variants:
+          configured_variants.nil? ? nil : Immutable.strings(configured_variants),
+        executable: executable.nil? ? nil : Immutable.string(executable)
+      )
+    end
+  end
+
+  RouteProbeResult = Data.define(
+    :provider, :ready, :installed, :executable, :version,
+    :minimum_version, :auth_configuration, :route,
+    :route_available, :available_variants,
+    :capability_evidence, :diagnostic
+  ) do
+    def initialize(provider:, ready:, installed:, executable:, version:,
+                   minimum_version:, auth_configuration:, route:,
+                   route_available:, available_variants:,
+                   capability_evidence:, diagnostic: nil)
+      super(
+        provider: provider.to_sym,
+        ready: ready == true,
+        installed: installed == true,
+        executable: Immutable.string(executable),
+        version: version.nil? ? nil : Immutable.string(version),
+        minimum_version:
+          minimum_version.nil? ? nil : Immutable.string(minimum_version),
+        auth_configuration: auth_configuration,
+        route: route,
+        route_available: route_available == true,
+        available_variants: Immutable.strings(available_variants),
+        capability_evidence: Array(capability_evidence).freeze,
+        diagnostic:
+          diagnostic.nil? ? nil : Immutable.string(diagnostic)
+      )
+    end
+  end
+
+  class PreparedInvocation
+    attr_reader :invocation, :environment, :credential_environment_keys,
+                :invocation_root, :generated_paths, :configuration_path,
+                :requested_route, :configuration_source, :probe_result,
+                :executable
+
+    def initialize(invocation:, environment:, credential_environment_keys:,
+                   invocation_root:, generated_paths:, configuration_path:,
+                   requested_route:, configuration_source:, probe_result:,
+                   cleanup:, executable: nil)
+      @invocation = invocation
+      @environment = Immutable.hash(environment)
+      @credential_environment_keys =
+        Immutable.strings(credential_environment_keys)
+      @invocation_root = Immutable.string(invocation_root)
+      @generated_paths = Immutable.strings(generated_paths)
+      @configuration_path = Immutable.string(configuration_path)
+      @requested_route = requested_route
+      @configuration_source =
+        configuration_source.nil? ? nil : Immutable.string(configuration_source)
+      @probe_result = probe_result
+      @executable = Immutable.string(executable || invocation.argv.fetch(0))
+      @cleanup = cleanup
+      freeze
+    end
+
+    def environment_for(env: ENV)
+      selected = credential_environment_keys.each_with_object({}) do |key, values|
+        value = env[key]
+        values[key] = value.to_s unless value.to_s.empty?
+      end
+      selected.merge(environment).freeze
+    end
+
+    def cleanup!
+      @cleanup.call
+      nil
+    end
+  end
+
+  TerminationEvidence = Data.define(
+    :exit_code, :timed_out, :cancelled, :signal
+  ) do
+    def initialize(exit_code:, timed_out: false, cancelled: false, signal: nil)
+      unless exit_code.nil? || exit_code.is_a?(Integer)
+        raise ArgumentError, "exit_code must be an Integer or nil"
+      end
+
+      super(
+        exit_code: exit_code,
+        timed_out: timed_out == true,
+        cancelled: cancelled == true,
+        signal: signal.nil? ? nil : Immutable.string(signal)
+      )
+    end
+
+    def success?
+      !timed_out && !cancelled && signal.nil? && exit_code == 0
+    end
+  end
+
+  CapturedResult = Data.define(
+    :stdout, :stderr, :termination, :inspection_output
+  ) do
+    def initialize(stdout:, stderr:, termination:, inspection_output: nil)
+      unless termination.is_a?(TerminationEvidence)
+        raise ArgumentError, "termination must be TerminationEvidence"
+      end
+
+      super(
+        stdout: Immutable.string(stdout),
+        stderr: Immutable.string(stderr),
+        termination: termination,
+        inspection_output:
+          inspection_output.nil? ? nil : Immutable.string(inspection_output)
+      )
+    end
+  end
+
+  NormalizedUsage = Data.define(
+    :input, :output, :cache_read, :cache_write, :reasoning,
+    :input_includes_cache_read, :input_includes_cache_write,
+    :output_includes_reasoning, :cost
+  ) do
+    def initialize(input: nil, output: nil, cache_read: nil, cache_write: nil,
+                   reasoning: nil, input_includes_cache_read: nil,
+                   input_includes_cache_write: nil,
+                   output_includes_reasoning: nil,
+                   provider_reported_cost: nil, cost: nil)
+      if !provider_reported_cost.nil? && !cost.nil? && provider_reported_cost != cost
+        raise ArgumentError, "provider_reported_cost and cost disagree"
+      end
+      super(
+        input: number(input, :input, integer: true),
+        output: number(output, :output, integer: true),
+        cache_read: number(cache_read, :cache_read, integer: true),
+        cache_write: number(cache_write, :cache_write, integer: true),
+        reasoning: number(reasoning, :reasoning, integer: true),
+        input_includes_cache_read:
+          boolean(input_includes_cache_read, :input_includes_cache_read),
+        input_includes_cache_write:
+          boolean(input_includes_cache_write, :input_includes_cache_write),
+        output_includes_reasoning:
+          boolean(output_includes_reasoning, :output_includes_reasoning),
+        cost: number(
+          provider_reported_cost.nil? ? cost : provider_reported_cost,
+          :provider_reported_cost,
+          integer: false
+        )
+      )
+    end
+
+    def cached
+      return nil if cache_read.nil? || cache_write.nil?
+
+      cache_read + cache_write
+    end
+
+    alias provider_reported_cost cost
+
+    private
+
+    def number(value, label, integer:)
+      return nil if value.nil?
+      valid = integer ? value.is_a?(Integer) : value.is_a?(Numeric)
+      valid &&= value.finite? if value.respond_to?(:finite?)
+      unless valid && value >= 0
+        raise ArgumentError, "#{label} must be a non-negative number or nil"
+      end
+
+      value
+    end
+
+
+    def boolean(value, label)
+      return nil if value.nil?
+      return value if value == true || value == false
+
+      raise ArgumentError, "#{label} must be true, false, or nil"
+    end
+  end
+
+  RouteIdentity = Data.define(:requested, :actual, :resolution_status) do
+    RESOLUTION_STATUSES = %i[unobserved matched resolved_differently].freeze
+
+    def initialize(requested:, actual: nil, resolution_status: nil)
+      requested_route = requested.is_a?(Route) ? requested : Route.parse(requested)
+      actual_route =
+        if actual.nil?
+          nil
+        elsif actual.is_a?(Route)
+          actual
+        else
+          Route.parse(actual)
+        end
+      status = resolution_status&.to_sym ||
+        (actual_route.nil? ? :unobserved :
+          (requested_route == actual_route ? :matched : :resolved_differently))
+      unless RESOLUTION_STATUSES.include?(status)
+        raise ArgumentError, "invalid route resolution status"
+      end
+
+      super(
+        requested: requested_route,
+        actual: actual_route,
+        resolution_status: status
+      )
+    end
+  end
+
+  ParsedRun = Data.define(
+    :session_id, :terminal_message_id, :terminal_reason,
+    :final_message, :final_message_truncated, :preliminary_usage, :unknown_events
+  ) do
+    def initialize(session_id:, terminal_message_id:, terminal_reason:,
+                   final_message:, preliminary_usage:, unknown_events: [],
+                   final_message_truncated: false)
+      unless preliminary_usage.is_a?(NormalizedUsage)
+        raise ArgumentError, "preliminary_usage must be NormalizedUsage"
+      end
+
+      super(
+        session_id: Immutable.string(session_id),
+        terminal_message_id: Immutable.string(terminal_message_id),
+        terminal_reason: Immutable.string(terminal_reason),
+        final_message: Immutable.string(final_message),
+        final_message_truncated: final_message_truncated == true,
+        preliminary_usage: preliminary_usage,
+        unknown_events: Immutable.strings(unknown_events)
+      )
+    end
+  end
+
+  InspectionCommand = Data.define(
+    :argv, :stdin_data, :environment, :credential_environment_keys,
+    :session_id, :message_id
+  ) do
+    def initialize(argv:, environment:, credential_environment_keys:,
+                   session_id:, message_id:, stdin_data: nil)
+      super(
+        argv: Immutable.strings(argv),
+        stdin_data: stdin_data.nil? ? nil : Immutable.string(stdin_data),
+        environment: Immutable.hash(environment),
+        credential_environment_keys:
+          Immutable.strings(credential_environment_keys),
+        session_id: Immutable.string(session_id),
+        message_id: Immutable.string(message_id)
+      )
+    end
+
+    def environment_for(env: ENV)
+      selected = credential_environment_keys.each_with_object({}) do |key, values|
+        value = env[key]
+        values[key] = value.to_s unless value.to_s.empty?
+      end
+      selected.merge(environment).freeze
+    end
+  end
+
+  NormalizedOutcome = Data.define(
+    :provider, :launcher_identity, :kind, :termination,
+    :final_message, :final_message_truncated, :identity, :usage, :diagnostic,
+    :unknown_events, :session_id, :message_id
+  ) do
+    KINDS = %i[
+      completed authentication_failure configuration_failure cli_failure
+      malformed_output cancelled timed_out
+    ].freeze
+
+    def initialize(provider:, launcher_identity:, kind:, termination:,
+                   final_message: nil, identity:, usage: nil, diagnostic: nil,
+                   unknown_events: [], session_id: nil, message_id: nil,
+                   final_message_truncated: false)
+      normalized_kind = kind.to_sym
+      unless KINDS.include?(normalized_kind)
+        raise ArgumentError, "invalid normalized outcome kind"
+      end
+      unless termination.is_a?(TerminationEvidence)
+        raise ArgumentError, "termination must be TerminationEvidence"
+      end
+      unless identity.is_a?(RouteIdentity)
+        raise ArgumentError, "identity must be RouteIdentity"
+      end
+      unless usage.nil? || usage.is_a?(NormalizedUsage)
+        raise ArgumentError, "usage must be NormalizedUsage or nil"
+      end
+
+      super(
+        provider: provider.to_sym,
+        launcher_identity: Immutable.string(launcher_identity),
+        kind: normalized_kind,
+        termination: termination,
+        final_message:
+          final_message.nil? ? nil : Immutable.string(final_message),
+        final_message_truncated: final_message_truncated == true,
+        identity: identity,
+        usage: usage,
+        diagnostic: diagnostic.nil? ? nil : Immutable.string(diagnostic),
+        unknown_events: Immutable.strings(unknown_events),
+        session_id: session_id.nil? ? nil : Immutable.string(session_id),
+        message_id: message_id.nil? ? nil : Immutable.string(message_id)
+      )
+    end
+
+    def completed?
+      kind == :completed
+    end
+  end
 end

data/lib/agent_cli_runtime/version.rb

@@ -1,3 +1,3 @@
 module AgentCliRuntime
-  VERSION = "0.1.1".freeze
+  VERSION = "0.2.4".freeze
 end

data/lib/agent_cli_runtime.rb

@@ -8,10 +8,16 @@ end
 
 require "agent_cli_runtime/redactor"
 require "agent_cli_runtime/usage_extractors"
+require "agent_cli_runtime/error_extractors"
+require "agent_cli_runtime/opencode/result_parser"
 require "agent_cli_runtime/profile"
 require "agent_cli_runtime/profiles"
 require "agent_cli_runtime/probe"
 require "agent_cli_runtime/runtime"
+require "agent_cli_runtime/opencode/probe"
+require "agent_cli_runtime/opencode/permissions"
+require "agent_cli_runtime/opencode/overlay"
+require "agent_cli_runtime/opencode/inspection"
 require "agent_cli_runtime/cli"
 
 module AgentCliRuntime
@@ -21,8 +27,8 @@ module AgentCliRuntime
     Runtime.compile(request)
   end
 
-  def prepare!(profile)
-    Runtime.prepare!(profile)
+  def prepare!(profile, env: ENV)
+    Runtime.prepare!(profile, env:)
   end
 
   def require_capability!(profile, capability)
@@ -33,12 +39,32 @@ module AgentCliRuntime
     Runtime.extract_usage(profile, event)
   end
 
+  def extract_provider_error(profile, event)
+    Runtime.extract_provider_error(profile, event)
+  end
+
   def observe(profile, result)
     Runtime.observe(profile, result)
   end
 
+  def parse_run(profile, stdout:)
+    Runtime.parse_run(profile, stdout:)
+  end
+
+  def prepare_inspection(prepared, parsed_run)
+    OpenCode::Inspection.compile(prepared, parsed_run)
+  end
+
+  def normalize(profile, captured, requested_route:)
+    Runtime.normalize(profile, captured, requested_route:)
+  end
+
   def probe(profile, home: nil, env: ENV)
-    Probe.call(profile, home: home, env: env)
+    if profile.is_a?(ProbeRequest)
+      OpenCode::Probe.call(profile, env: env)
+    else
+      Probe.call(profile, home: home, env: env)
+    end
   end
 
   def probe_all(home: nil, env: ENV)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-cli-runtime
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.4
 platform: ruby
 authors:
 - Ivan Kuznetsov
@@ -64,10 +64,11 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.0'
 description: |
-  Agent CLI Runtime provides immutable profiles, invocation compilation,
-  local prerequisite probes, capability evidence, usage extraction, and
-  result normalization for Claude Code, Codex CLI, Pi, and Grok CLI. It does
-  not spawn agents or claim live provider health, quota, or credential validity.
+  Agent CLI Runtime gives Ruby applications one stable integration layer for
+  local coding-agent CLIs. It builds provider-specific commands from a shared
+  request model, checks local versions and named capabilities, and normalizes
+  usage and results afterward. Centralized profiles, environment rules, and
+  parsers make agent providers easier to add, switch, and upgrade.
 email:
 - ivan@ikuznetsov.com
 executables:
@@ -82,7 +83,13 @@ files:
 - exe/agent-runtime
 - lib/agent_cli_runtime.rb
 - lib/agent_cli_runtime/cli.rb
+- lib/agent_cli_runtime/error_extractors.rb
 - lib/agent_cli_runtime/errors.rb
+- lib/agent_cli_runtime/opencode/inspection.rb
+- lib/agent_cli_runtime/opencode/overlay.rb
+- lib/agent_cli_runtime/opencode/permissions.rb
+- lib/agent_cli_runtime/opencode/probe.rb
+- lib/agent_cli_runtime/opencode/result_parser.rb
 - lib/agent_cli_runtime/probe.rb
 - lib/agent_cli_runtime/profile.rb
 - lib/agent_cli_runtime/profiles.rb
@@ -117,5 +124,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Provider-neutral contracts for installed agent CLIs
+summary: One Ruby API for Claude Code, Codex CLI, Pi, Grok CLI, and OpenCode
 test_files: []