agent-cli-runtime 0.1.0

data/lib/agent_cli_runtime/runtime.rb

@@ -0,0 +1,289 @@
+module AgentCliRuntime
+  module Runtime
+    module_function
+
+    def compile(request)
+      unless request.is_a?(Request)
+        raise ArgumentError,
+              "request must be an AgentCliRuntime::Request"
+      end
+
+      profile = Profiles.resolve(request.profile)
+      evidence = [ supported_evidence(profile, :headless) ]
+      argv = [ request.executable || profile.bin ]
+      prompt_style = profile.prompt_style
+      argv << profile.headless_flag
+      argv << request.prompt if prompt_style == :headless_flag_value
+
+      argv.concat(
+        permission_arguments(
+          profile, request.permission_mode, evidence,
+          trusted_arguments: request.permission_arguments
+        )
+      )
+      argv.concat(directory_arguments(profile, request, evidence))
+      argv.concat(tool_scope_arguments(profile, request, evidence))
+      argv.concat(budget_arguments(profile, request.max_budget_usd, evidence))
+      argv.concat(identity_arguments(profile, request, evidence))
+
+      request.capabilities.each do |capability|
+        capability_evidence = require_capability!(profile, capability)
+        evidence << capability_evidence
+        argv.concat(capability_evidence.arguments)
+      end
+
+      unless request.raw_cli_arguments.empty?
+        unless profile.raw_cli_arguments_supported?
+          unsupported!(
+            profile, :raw_cli_arguments,
+            "agent profile #{profile.name.inspect} does not accept raw CLI arguments"
+          )
+        end
+        evidence << supported_evidence(
+          profile, :raw_cli_arguments, request.raw_cli_arguments
+        )
+        argv.concat(request.raw_cli_arguments)
+      end
+      argv.concat(request.trusted_cli_arguments)
+      argv.concat(profile.output_format_flags) if request.include_output_format
+      argv << (prompt_style == :stdin ? "-" : request.prompt) unless
+        prompt_style == :headless_flag_value
+
+      CompiledInvocation.new(
+        argv: request.command_prefix + argv,
+        stdin_data: prompt_style == :stdin ? request.prompt : nil,
+        provider: profile.name,
+        launcher_identity: profile.launcher_identity,
+        capability_evidence: evidence
+      )
+    rescue Error
+      raise
+    rescue StandardError => e
+      profile = Profiles.resolve(request.profile) if request.is_a?(Request)
+      compilation_error!(profile, e)
+    end
+
+    def prepare!(profile)
+      resolved = Profiles.resolve(profile)
+      result = Probe.call(resolved)
+      return result if result.ready
+
+      evidence = unsupported_evidence(
+        resolved, :probe, result.diagnostic || "local prerequisites unavailable"
+      )
+      raise ProbeError.new(
+        "agent profile #{resolved.name.inspect} probe failed: #{evidence.diagnostic}",
+        evidence: evidence
+      )
+    end
+
+    def require_capability!(profile, capability)
+      resolved = Profiles.resolve(profile)
+      arguments = resolved.require_cli_capability!(capability)
+      supported_evidence(resolved, capability, arguments)
+    rescue UnknownProvider
+      raise
+    rescue Error => e
+      evidence = unsupported_evidence(
+        resolved, capability, Redactor.diagnostic(e)
+      )
+      raise UnsupportedCapability.new(
+        "agent profile #{resolved.name.inspect} cannot provide " \
+        "#{capability.to_sym.inspect}: #{evidence.diagnostic}",
+        evidence: evidence
+      ), cause: e
+    end
+
+    def extract_usage(profile, event)
+      resolved = Profiles.resolve(profile)
+      begin
+        normalize_usage(resolved.extract_usage_event(event))
+      rescue StandardError
+        nil
+      end
+    end
+
+    def observe(profile, result)
+      resolved = Profiles.resolve(profile)
+      raw = result.is_a?(Hash) ? result : {}
+      ObservableResult.new(
+        provider: resolved.name,
+        launcher_identity: resolved.launcher_identity,
+        exit_code: raw[:exit_code],
+        timed_out: raw[:timed_out],
+        status: raw[:status],
+        usage: normalize_usage(raw[:usage]),
+        final_message: raw[:final_message],
+        diagnostic: Redactor.diagnostic(
+          raw[:error_message] || raw[:limit_text]
+        )
+      )
+    end
+
+    def supported_evidence(profile, capability, arguments = [])
+      CapabilityEvidence.new(
+        capability: capability,
+        supported: true,
+        provider: profile.name,
+        launcher_identity: profile.launcher_identity,
+        arguments: arguments
+      )
+    end
+
+    def unsupported_evidence(profile, capability, diagnostic)
+      CapabilityEvidence.new(
+        capability: capability,
+        supported: false,
+        provider: profile&.name || :unknown,
+        launcher_identity: profile&.launcher_identity || "unknown",
+        diagnostic: Redactor.diagnostic(diagnostic)
+      )
+    end
+
+    def permission_arguments(profile, permission_mode, evidence,
+                             trusted_arguments: nil)
+      arguments =
+        if trusted_arguments
+          trusted_arguments
+        else
+          profile.permission_flags(permission_mode)
+        end
+      capability =
+        permission_mode&.tr("-", "_")&.to_sym || :permission_bypass
+      evidence << supported_evidence(profile, capability, arguments)
+      arguments
+    rescue ArgumentError => e
+      unsupported!(
+        profile, permission_mode&.tr("-", "_")&.to_sym || :permission, e
+      )
+    end
+    private_class_method :permission_arguments
+
+    def directory_arguments(profile, request, evidence)
+      return [] if request.add_dirs.empty?
+
+      unless profile.add_dir_flag
+        if request.require_add_dirs
+          unsupported!(
+            profile, :add_directory,
+            "agent profile #{profile.name.inspect} cannot constrain additional directories"
+          )
+        end
+        evidence << unsupported_evidence(
+          profile, :add_directory,
+          "unsupported; directories intentionally omitted"
+        )
+        return []
+      end
+
+      arguments =
+        request.add_dirs.flat_map { |directory| [ profile.add_dir_flag, directory ] }
+      evidence << supported_evidence(profile, :add_directory, arguments)
+      arguments
+    end
+    private_class_method :directory_arguments
+
+    def tool_scope_arguments(profile, request, evidence)
+      arguments = []
+      {
+        allowed_tools: [ request.allowed_tools, :allowed ],
+        disallowed_tools: [ request.disallowed_tools, :disallowed ]
+      }.each do |capability, (tools, scope)|
+        value = tool_csv(tools)
+        next unless value
+
+        flag = profile.tool_scope_flags[scope]
+        unless flag
+          unsupported!(
+            profile, capability,
+            "agent profile #{profile.name.inspect} cannot enforce #{scope} tool scope"
+          )
+        end
+        scoped_arguments = [ flag, value ]
+        evidence << supported_evidence(profile, capability, scoped_arguments)
+        arguments.concat(scoped_arguments)
+      end
+      arguments
+    end
+    private_class_method :tool_scope_arguments
+
+    def budget_arguments(profile, max_budget_usd, evidence)
+      return [] if max_budget_usd.nil?
+      unless profile.budget_flag
+        unsupported!(
+          profile, :budget,
+          "agent profile #{profile.name.inspect} cannot enforce a native budget"
+        )
+      end
+
+      arguments = [ profile.budget_flag, max_budget_usd.to_s ]
+      evidence << supported_evidence(profile, :budget, arguments)
+      arguments
+    end
+    private_class_method :budget_arguments
+
+    def identity_arguments(profile, request, evidence)
+      arguments = request.identity_arguments.dup
+      return arguments unless request.model || request.effort
+      unless request.model
+        unsupported!(
+          profile, :effort,
+          "effort requires an explicit model in an invocation request"
+        )
+      end
+
+      identity = profile.identity_arguments(
+        model: request.model,
+        effort: request.effort,
+        pin_model: request.pin_model
+      )
+      evidence << supported_evidence(profile, :model, identity.native_arguments)
+      evidence << supported_evidence(profile, :effort) if request.effort
+      arguments.concat(identity.native_arguments)
+    rescue UnsupportedCapability => e
+      capability = request.effort && !profile.effort_argument_builder ? :effort : :model
+      unsupported!(profile, capability, e)
+    end
+    private_class_method :identity_arguments
+
+    def tool_csv(tools)
+      values = Array(tools).compact.map(&:to_s).reject(&:empty?).uniq
+      values.empty? ? nil : values.join(",")
+    end
+    private_class_method :tool_csv
+
+    def normalize_usage(usage)
+      return nil unless usage.is_a?(Hash)
+
+      input = usage.key?(:input) ? usage[:input] : usage["input"]
+      output = usage.key?(:output) ? usage[:output] : usage["output"]
+      cached = usage.key?(:cached) ? usage[:cached] : usage["cached"]
+      model = usage.key?(:model) ? usage[:model] : usage["model"]
+      {
+        input: [ input.to_i, 0 ].max,
+        output: [ output.to_i, 0 ].max,
+        cached: [ cached.to_i, 0 ].max,
+        model: model&.to_s&.dup&.freeze
+      }.freeze
+    end
+    private_class_method :normalize_usage
+
+    def unsupported!(profile, capability, diagnostic)
+      evidence = unsupported_evidence(profile, capability, diagnostic)
+      raise UnsupportedCapability.new(
+        evidence.diagnostic,
+        evidence: evidence
+      )
+    end
+    private_class_method :unsupported!
+
+    def compilation_error!(profile, error)
+      evidence = unsupported_evidence(profile, :compilation, error)
+      raise CompilationError.new(
+        "agent invocation compilation failed: #{evidence.diagnostic}",
+        evidence: evidence
+      ), cause: error
+    end
+    private_class_method :compilation_error!
+  end
+end

data/lib/agent_cli_runtime/usage_extractors.rb

@@ -0,0 +1,115 @@
+module AgentCliRuntime
+  module UsageExtractors
+    module_function
+
+    CLAUDE = lambda do |event|
+      next nil unless event.is_a?(Hash)
+
+      usage = usage_hash(event)
+      if event["type"] == "result" && usage
+        usage_result(event, usage, model_from(event))
+      elsif event["type"] == "stream_event" && usage
+        usage_result(event, usage, model_from(event))
+      end
+    end
+
+    CODEX = lambda do |event|
+      next nil unless event.is_a?(Hash)
+
+      usage = usage_hash(event)
+      usage_result(event, usage, model_from(event)) if usage
+    end
+
+    PI = lambda do |event|
+      next nil unless event.is_a?(Hash)
+
+      usage = usage_hash(event)
+      usage_result(event, usage, model_from(event)) if usage
+    end
+
+    GROK = lambda do |event|
+      next nil unless event.is_a?(Hash)
+
+      usage = usage_hash(event)
+      usage_result(event, usage, model_from(event)) if usage
+    end
+
+    def usage_hash(event)
+      candidates = [
+        event["usage"],
+        event["token_usage"],
+        event.dig("event", "usage"),
+        event.dig("event", "message", "usage"),
+        event.dig("info", "usage"),
+        event.dig("info", "total_token_usage"),
+        event.dig("response", "usage"),
+        event.dig("item", "usage")
+      ]
+      candidates.find { |value| value.is_a?(Hash) }
+    end
+
+    def usage_result(event, usage, model)
+      {
+        input: token_count(
+          usage, "input_tokens", "inputTokens", "prompt_tokens", "promptTokens"
+        ),
+        output: token_count(
+          usage, "output_tokens", "outputTokens", "completion_tokens",
+          "completionTokens"
+        ),
+        cached: cached_tokens(usage),
+        model: model || model_from_usage(usage) || model_from(event)
+      }
+    end
+
+    def cached_tokens(usage)
+      direct = token_count(
+        usage, "cached", "cached_tokens", "cachedTokens",
+        "cached_input_tokens", "cachedInputTokens"
+      )
+      return direct if direct.positive?
+
+      token_count(usage, "cache_read_input_tokens", "cacheReadInputTokens") +
+        token_count(usage, "cache_creation_input_tokens", "cacheCreationInputTokens") +
+        token_count(
+          nested_hash(usage, "prompt_tokens_details"), "cached_tokens", "cachedTokens"
+        ) +
+        token_count(
+          nested_hash(usage, "input_tokens_details"), "cached_tokens", "cachedTokens"
+        )
+    end
+
+    def token_count(hash, *keys)
+      return 0 unless hash.is_a?(Hash)
+
+      key = keys.find { |candidate| hash.key?(candidate) }
+      key ? hash[key].to_i : 0
+    end
+
+    def nested_hash(hash, key)
+      value = hash[key]
+      value.is_a?(Hash) ? value : {}
+    end
+
+    def model_from(event)
+      model_usage = event["modelUsage"]
+      if model_usage.is_a?(Hash) && !model_usage.empty?
+        return model_usage.keys.first.to_s
+      end
+
+      candidates = [
+        event["model"],
+        event.dig("message", "model"),
+        event.dig("event", "message", "model"),
+        event.dig("response", "model"),
+        event.dig("item", "model")
+      ]
+      candidates.find { |value| !value.to_s.empty? }&.to_s
+    end
+
+    def model_from_usage(usage)
+      value = usage["model"] || usage["model_name"] || usage["modelName"]
+      value.to_s.empty? ? nil : value.to_s
+    end
+  end
+end

data/lib/agent_cli_runtime/values.rb

@@ -0,0 +1,174 @@
+module AgentCliRuntime
+  module Immutable
+    module_function
+
+    def string(value)
+      string = value.to_s
+      string.frozen? ? string : string.dup.freeze
+    end
+
+    def strings(values)
+      Array(values).map { |value| string(value) }.freeze
+    end
+
+    def symbols(values)
+      Array(values).map(&:to_sym).uniq.freeze
+    end
+  end
+  private_constant :Immutable
+
+  CapabilityEvidence = Data.define(
+    :capability, :supported, :provider, :launcher_identity, :arguments, :diagnostic
+  ) do
+    def initialize(capability:, supported:, provider:, launcher_identity:,
+                   arguments: [], diagnostic: nil)
+      super(
+        capability: capability.to_sym,
+        supported: supported == true,
+        provider: provider.to_sym,
+        launcher_identity: Immutable.string(launcher_identity),
+        arguments: Immutable.strings(arguments),
+        diagnostic: diagnostic.nil? ? nil : Immutable.string(diagnostic)
+      )
+    end
+  end
+
+  IdentityArguments = Data.define(
+    :model, :requested_effort, :effective_effort, :effort_supported,
+    :model_pinned, :native_arguments
+  ) do
+    def initialize(model:, requested_effort:, effective_effort:, effort_supported:,
+                   model_pinned:, native_arguments:)
+      super(
+        model: Immutable.string(model),
+        requested_effort:
+          requested_effort.nil? ? nil : Immutable.string(requested_effort),
+        effective_effort:
+          effective_effort.nil? ? nil : Immutable.string(effective_effort),
+        effort_supported: effort_supported == true,
+        model_pinned: model_pinned == true,
+        native_arguments: Immutable.strings(native_arguments)
+      )
+    end
+  end
+
+  Request = Data.define(
+    :profile, :prompt, :permission_mode, :permission_arguments,
+    :add_dirs, :require_add_dirs,
+    :allowed_tools, :disallowed_tools, :max_budget_usd,
+    :model, :effort, :pin_model, :identity_arguments,
+    :capabilities, :raw_cli_arguments, :trusted_cli_arguments,
+    :executable, :command_prefix, :include_output_format
+  ) do
+    def initialize(profile:, prompt:, permission_mode: nil, permission_arguments: nil,
+                   add_dirs: [], require_add_dirs: false, allowed_tools: nil,
+                   disallowed_tools: nil, max_budget_usd: nil, model: nil,
+                   effort: nil, pin_model: true, identity_arguments: [],
+                   capabilities: [], raw_cli_arguments: [],
+                   trusted_cli_arguments: [], executable: nil,
+                   command_prefix: [], include_output_format: true)
+      super(
+        profile: profile,
+        prompt: Immutable.string(prompt),
+        permission_mode:
+          permission_mode.nil? ? nil : Immutable.string(permission_mode),
+        permission_arguments:
+          permission_arguments.nil? ? nil : Immutable.strings(permission_arguments),
+        add_dirs: Immutable.strings(add_dirs),
+        require_add_dirs: require_add_dirs == true,
+        allowed_tools: Immutable.strings(allowed_tools),
+        disallowed_tools: Immutable.strings(disallowed_tools),
+        max_budget_usd: max_budget_usd,
+        model: model.nil? ? nil : Immutable.string(model),
+        effort: effort.nil? ? nil : Immutable.string(effort),
+        pin_model: pin_model != false,
+        identity_arguments: Immutable.strings(identity_arguments),
+        capabilities: Immutable.symbols(capabilities),
+        raw_cli_arguments: Immutable.strings(raw_cli_arguments),
+        trusted_cli_arguments: Immutable.strings(trusted_cli_arguments),
+        executable: executable.nil? ? nil : Immutable.string(executable),
+        command_prefix: Immutable.strings(command_prefix),
+        include_output_format: include_output_format != false
+      )
+    end
+  end
+
+  CompiledInvocation = Data.define(
+    :argv, :stdin_data, :provider, :launcher_identity, :capability_evidence
+  ) do
+    def initialize(argv:, stdin_data:, provider:, launcher_identity:,
+                   capability_evidence:)
+      super(
+        argv: Immutable.strings(argv),
+        stdin_data: stdin_data.nil? ? nil : Immutable.string(stdin_data),
+        provider: provider.to_sym,
+        launcher_identity: Immutable.string(launcher_identity),
+        capability_evidence: Array(capability_evidence).freeze
+      )
+    end
+  end
+
+  AuthConfiguration = Data.define(:status, :source, :diagnostic) do
+    STATUSES = %i[configured missing not_checked].freeze
+
+    def initialize(status:, source: nil, diagnostic: nil)
+      normalized_status = status.to_sym
+      unless STATUSES.include?(normalized_status)
+        raise ArgumentError,
+              "unknown auth configuration status #{status.inspect}; valid: #{STATUSES.inspect}"
+      end
+
+      super(
+        status: normalized_status,
+        source: source.nil? ? nil : Immutable.string(source),
+        diagnostic: diagnostic.nil? ? nil : Immutable.string(diagnostic)
+      )
+    end
+
+    def configured?
+      status == :configured
+    end
+  end
+
+  ProbeResult = Data.define(
+    :provider, :ready, :installed, :executable, :version, :minimum_version,
+    :auth_configuration, :capability_evidence, :diagnostic
+  ) do
+    def initialize(provider:, ready:, installed:, executable:, version:,
+                   minimum_version:, auth_configuration:, capability_evidence:,
+                   diagnostic:)
+      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,
+        capability_evidence: Array(capability_evidence).freeze,
+        diagnostic: diagnostic.nil? ? nil : Immutable.string(diagnostic)
+      )
+    end
+  end
+
+  ObservableResult = Data.define(
+    :provider, :launcher_identity, :exit_code, :timed_out, :status,
+    :usage, :final_message, :diagnostic
+  ) do
+    def initialize(provider:, launcher_identity:, exit_code:, timed_out:,
+                   status:, usage:, final_message:, diagnostic:)
+      super(
+        provider: provider.to_sym,
+        launcher_identity: Immutable.string(launcher_identity),
+        exit_code: exit_code,
+        timed_out: timed_out == true,
+        status: status&.to_sym,
+        usage: usage&.dup&.freeze,
+        final_message:
+          final_message.nil? ? nil : Immutable.string(final_message),
+        diagnostic: diagnostic.nil? ? nil : Immutable.string(diagnostic)
+      )
+    end
+  end
+end

data/lib/agent_cli_runtime/version.rb

@@ -0,0 +1,3 @@
+module AgentCliRuntime
+  VERSION = "0.1.0".freeze
+end

data/lib/agent_cli_runtime.rb

@@ -0,0 +1,47 @@
+require "agent_cli_runtime/version"
+require "agent_cli_runtime/errors"
+require "agent_cli_runtime/values"
+
+module AgentCliRuntime
+  DIAGNOSTIC_BYTES = 512
+end
+
+require "agent_cli_runtime/redactor"
+require "agent_cli_runtime/usage_extractors"
+require "agent_cli_runtime/profile"
+require "agent_cli_runtime/profiles"
+require "agent_cli_runtime/probe"
+require "agent_cli_runtime/runtime"
+require "agent_cli_runtime/cli"
+
+module AgentCliRuntime
+  module_function
+
+  def compile(request)
+    Runtime.compile(request)
+  end
+
+  def prepare!(profile)
+    Runtime.prepare!(profile)
+  end
+
+  def require_capability!(profile, capability)
+    Runtime.require_capability!(profile, capability)
+  end
+
+  def extract_usage(profile, event)
+    Runtime.extract_usage(profile, event)
+  end
+
+  def observe(profile, result)
+    Runtime.observe(profile, result)
+  end
+
+  def probe(profile, home: nil, env: ENV)
+    Probe.call(profile, home: home, env: env)
+  end
+
+  def probe_all(home: nil, env: ENV)
+    Probe.all(home: home, env: env)
+  end
+end