agent-cli-runtime 0.2.0 → 0.2.4

data/lib/agent_cli_runtime/runtime.rb

@@ -46,12 +46,23 @@ module AgentCliRuntime
       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
+      stdin_data =
+        case prompt_style
+        when :positional
+          argv << request.prompt
+          nil
+        when :headless_flag_value
+          nil
+        when :stdin
+          argv << "-"
+          request.prompt
+        when :piped_stdin
+          request.prompt
+        end
 
       CompiledInvocation.new(
         argv: request.command_prefix + argv,
-        stdin_data: prompt_style == :stdin ? request.prompt : nil,
+        stdin_data:,
         provider: profile.name,
         launcher_identity: profile.launcher_identity,
         capability_evidence: evidence
@@ -107,6 +118,51 @@ module AgentCliRuntime
       end
     end
 
+    # A provider failure seen mid-stream, normalized to
+    # {kind:, provider:, status_code:, message:}, or nil when the event is
+    # clean. Callers use this to tell a provider-side stop (quota, credit
+    # ceiling, rate limit, model output truncation) apart from an agent that
+    # genuinely produced nothing: several CLIs report the former on the stream
+    # and still exit zero.
+    def extract_provider_error(profile, event)
+      resolved = Profiles.resolve(profile)
+      extracted = resolved.extract_error_event(event)
+      return nil if extracted.nil?
+
+      kind, text = normalize_extracted_error(extracted)
+      return nil if text.nil? || text.strip.empty?
+
+      {
+        kind: kind,
+        provider: resolved.name,
+        status_code: status_code_from(text),
+        message: Redactor.diagnostic(text)
+      }.freeze
+    end
+
+    def normalize_extracted_error(extracted)
+      return [ extracted.kind, extracted.message ] if extracted.is_a?(ExtractedFailure)
+      return [ failure_kind_from(extracted), extracted ] if extracted.is_a?(String)
+
+      [ nil, nil ]
+    end
+    private_class_method :normalize_extracted_error
+
+    def failure_kind_from(text)
+      status = status_code_from(text)
+      return :provider_limit if status == 402
+      return :rate_limited if status == 429
+
+      normalized = text.to_s.downcase
+      return :rate_limited if normalized.match?(/\brate[\s_-]*limit(?:ed|s)?\b/)
+      return :provider_limit if normalized.match?(
+        /\b(?:quota|billing|credits?|tokens?[\s_-]*limit|usage[\s_-]*limit)\b/
+      )
+
+      :provider_error
+    end
+    private_class_method :failure_kind_from
+
     def observe(profile, result)
       resolved = Profiles.resolve(profile)
       raw = result.is_a?(Hash) ? result : {}
@@ -267,22 +323,57 @@ module AgentCliRuntime
     end
     private_class_method :tool_csv
 
+    # Providers prefix the status onto the text ("402: {...}") or carry it in
+    # the embedded payload. Either is enough to classify without matching on
+    # human-readable wording, which differs per provider and changes freely.
+    def status_code_from(text)
+      value = text[/\A\s*(\d{3})\s*:/, 1] ||
+              text[/"(?:code|http_status)"\s*:\s*(\d{3})\b/, 1]
+      code = value.to_i
+      code.between?(100, 599) ? code : nil
+    end
+    private_class_method :status_code_from
+
     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"]
+      value = ->(key) { usage.key?(key) ? usage[key] : usage[key.to_s] }
       {
-        input: [ input.to_i, 0 ].max,
-        output: [ output.to_i, 0 ].max,
-        cached: [ cached.to_i, 0 ].max,
-        model: model&.to_s&.dup&.freeze
+        input: normalized_count(value.call(:input)),
+        output: normalized_count(value.call(:output)),
+        cached: normalized_count(value.call(:cached)),
+        cache_read: normalized_count(value.call(:cache_read)),
+        cache_write: normalized_count(value.call(:cache_write)),
+        reasoning: normalized_count(value.call(:reasoning)),
+        input_includes_cache_read: normalized_boolean(value.call(:input_includes_cache_read)),
+        input_includes_cache_write: normalized_boolean(value.call(:input_includes_cache_write)),
+        output_includes_reasoning: normalized_boolean(value.call(:output_includes_reasoning)),
+        model: value.call(:model)&.to_s&.dup&.freeze,
+        # Carried as a float: this is money, and normalized_count would round
+        # a fraction-of-a-cent charge to zero.
+        provider_reported_cost: normalized_cost(value.call(:provider_reported_cost))
       }.freeze
     end
     private_class_method :normalize_usage
 
+    def normalized_cost(value)
+      return nil unless value.is_a?(Numeric)
+
+      cost = value.to_f
+      cost if cost >= 0 && cost.finite?
+    end
+    private_class_method :normalized_cost
+
+    def normalized_count(value)
+      value.nil? ? nil : [ value.to_i, 0 ].max
+    end
+    private_class_method :normalized_count
+
+    def normalized_boolean(value)
+      value if value == true || value == false
+    end
+    private_class_method :normalized_boolean
+
     def unsupported!(profile, capability, diagnostic)
       evidence = unsupported_evidence(profile, capability, diagnostic)
       raise UnsupportedCapability.new(

data/lib/agent_cli_runtime/usage_extractors.rb

@@ -7,9 +7,9 @@ module AgentCliRuntime
 
       usage = usage_hash(event)
       if event["type"] == "result" && usage
-        usage_result(event, usage, model_from(event))
+        usage_result(event, usage, model_from(event), provider: :claude)
       elsif event["type"] == "stream_event" && usage
-        usage_result(event, usage, model_from(event))
+        usage_result(event, usage, model_from(event), provider: :claude)
       end
     end
 
@@ -17,21 +17,21 @@ module AgentCliRuntime
       next nil unless event.is_a?(Hash)
 
       usage = usage_hash(event)
-      usage_result(event, usage, model_from(event)) if usage
+      usage_result(event, usage, model_from(event), provider: :codex) 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
+      usage_result(event, usage, model_from(event), provider: :pi) 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
+      usage_result(event, usage, model_from(event), provider: :grok) if usage
     end
 
     def usage_hash(event)
@@ -40,6 +40,9 @@ module AgentCliRuntime
         event["token_usage"],
         event.dig("event", "usage"),
         event.dig("event", "message", "usage"),
+        # pi reports usage on the assistant message itself, not under an
+        # "event" envelope. Without this every pi run is unmetered.
+        event.dig("message", "usage"),
         event.dig("info", "usage"),
         event.dig("info", "total_token_usage"),
         event.dig("response", "usage"),
@@ -48,42 +51,126 @@ module AgentCliRuntime
       candidates.find { |value| value.is_a?(Hash) }
     end
 
-    def usage_result(event, usage, model)
+    def usage_result(event, usage, model, provider:)
+      cache_read = cache_read_tokens(usage)
+      cache_write = cache_write_tokens(usage)
+      aggregate_cached = aggregate_cached_tokens(usage)
+      reasoning = optional_token_count(
+        usage, "reasoning_tokens", "reasoningTokens"
+      )
+      reasoning ||= optional_token_count(
+        nested_hash(usage, "completion_tokens_details"),
+        "reasoning_tokens", "reasoningTokens"
+      )
       {
-        input: token_count(
-          usage, "input_tokens", "inputTokens", "prompt_tokens", "promptTokens"
+        # The bare "input"/"output" spellings are pi's and are matched last,
+        # so a provider using an explicit *_tokens key keeps its own reading.
+        input: optional_token_count(
+          usage, "input_tokens", "inputTokens", "prompt_tokens", "promptTokens",
+          "input"
         ),
-        output: token_count(
+        output: optional_token_count(
           usage, "output_tokens", "outputTokens", "completion_tokens",
-          "completionTokens"
+          "completionTokens", "output"
         ),
-        cached: cached_tokens(usage),
-        model: model || model_from_usage(usage) || model_from(event)
+        cached: aggregate_cached || complete_cached(cache_read, cache_write),
+        cache_read: cache_read,
+        cache_write: cache_write,
+        reasoning: reasoning,
+        input_includes_cache_read:
+          inclusion_or_inferred(
+            usage, "input_includes_cache_read",
+            inferred_input_cache_inclusion(provider, cache_read)
+          ),
+        input_includes_cache_write:
+          inclusion_or_inferred(
+            usage, "input_includes_cache_write",
+            inferred_input_cache_inclusion(provider, cache_write)
+          ),
+        output_includes_reasoning:
+          inclusion_or_inferred(
+            usage, "output_includes_reasoning",
+            inferred_reasoning_inclusion(provider, reasoning)
+          ),
+        model: model || model_from_usage(usage) || model_from(event),
+        provider_reported_cost: reported_cost(usage)
       }
     end
 
-    def cached_tokens(usage)
-      direct = token_count(
+    # A charge the provider itself reported for this turn, in USD. This is an
+    # observed amount, not an estimate from the pricing catalog, and it is the
+    # only cost available for a model the catalog does not carry — an
+    # OpenRouter-routed model, for one. OpenRouter sends a per-category
+    # breakdown carrying a total; other providers may send a scalar.
+    def reported_cost(usage)
+      value = usage["cost"] || usage["total_cost"] || usage["totalCost"]
+      value = value["total"] || value["total_cost"] if value.is_a?(Hash)
+      return nil unless value.is_a?(Numeric) || value.is_a?(String)
+
+      cost = begin
+        Float(value)
+      rescue ArgumentError, TypeError
+        nil
+      end
+      cost if cost && cost >= 0 && cost.finite?
+    end
+
+    def aggregate_cached_tokens(usage)
+      optional_token_count(
         usage, "cached", "cached_tokens", "cachedTokens",
         "cached_input_tokens", "cachedInputTokens"
       )
-      return direct if direct.positive?
+    end
+
+    def cache_read_tokens(usage)
+      optional_token_count(
+        usage, "cache_read_input_tokens", "cacheReadInputTokens"
+      ) || optional_token_count(
+        nested_hash(usage, "prompt_tokens_details"), "cached_tokens", "cachedTokens"
+      ) || optional_token_count(
+        nested_hash(usage, "input_tokens_details"), "cached_tokens", "cachedTokens"
+      ) || optional_token_count(usage, "cacheRead")
+    end
+
+    def cache_write_tokens(usage)
+      optional_token_count(
+        usage, "cache_creation_input_tokens", "cacheCreationInputTokens",
+        "cache_write_input_tokens", "cacheWriteInputTokens", "cacheWrite"
+      )
+    end
 
-      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"
-        )
+    def complete_cached(cache_read, cache_write)
+      return nil if cache_read.nil? || cache_write.nil?
+
+      cache_read + cache_write
     end
 
-    def token_count(hash, *keys)
-      return 0 unless hash.is_a?(Hash)
+    def inferred_input_cache_inclusion(provider, value)
+      return nil if value.nil?
+      return false if provider == :claude
+      return true if provider == :codex
+
+      nil
+    end
+
+    def inferred_reasoning_inclusion(provider, value)
+      return nil if value.nil?
+
+      provider == :codex ? true : nil
+    end
+
+    def inclusion_or_inferred(hash, key, inferred)
+      return inferred unless hash.is_a?(Hash) && hash.key?(key)
+
+      value = hash[key]
+      value if value == true || value == false
+    end
+
+    def optional_token_count(hash, *keys)
+      return nil unless hash.is_a?(Hash)
 
       key = keys.find { |candidate| hash.key?(candidate) }
-      key ? hash[key].to_i : 0
+      key ? hash[key].to_i : nil
     end
 
     def nested_hash(hash, key)
@@ -92,11 +179,6 @@ module AgentCliRuntime
     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"),
@@ -104,7 +186,12 @@ module AgentCliRuntime
         event.dig("response", "model"),
         event.dig("item", "model")
       ]
-      candidates.find { |value| !value.to_s.empty? }&.to_s
+      explicit = candidates.find { |value| !value.to_s.empty? }
+      return explicit.to_s if explicit
+
+      # Run totals may include helper models; their order is not agent identity.
+      model_usage = event["modelUsage"]
+      model_usage.keys.first.to_s if model_usage.is_a?(Hash) && model_usage.size == 1
     end
 
     def model_from_usage(usage)

data/lib/agent_cli_runtime/values.rb

@@ -81,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,
@@ -265,13 +271,14 @@ module AgentCliRuntime
     :configuration_path, :configuration,
     :credential_environment_keys, :credential_file,
     :permission_policy, :additional_read_roots,
-    :additional_write_roots, :edit_patterns, :plugins, :pure
+    :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: [], plugins: [], pure: true)
+                   additional_write_roots: [], edit_patterns: [],
+                   bash_patterns: [], plugins: [], pure: true)
       unless request.is_a?(Request)
         raise ArgumentError, "request must be an AgentCliRuntime::Request"
       end
@@ -294,6 +301,10 @@ module AgentCliRuntime
         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,
@@ -310,6 +321,7 @@ module AgentCliRuntime
         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
       )
@@ -318,11 +330,14 @@ module AgentCliRuntime
 
   ProbeRequest = Data.define(
     :profile, :route, :variant, :environment,
-    :credential_environment_keys, :credential_file_staged
+    :credential_environment_keys, :credential_file_staged,
+    :configured_variants, :executable
   ) do
     def initialize(profile:, route:, variant: nil, environment: {},
                    credential_environment_keys: [],
-                   credential_file_staged: false)
+                   credential_file_staged: false,
+                   configured_variants: nil,
+                   executable: nil)
       parsed_route = route.is_a?(Route) ? route : Route.parse(route)
       super(
         profile: profile,
@@ -331,7 +346,10 @@ module AgentCliRuntime
         environment: Immutable.hash(environment),
         credential_environment_keys:
           Immutable.strings(credential_environment_keys),
-        credential_file_staged: credential_file_staged == true
+        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
@@ -445,17 +463,35 @@ module AgentCliRuntime
   end
 
   NormalizedUsage = Data.define(
-    :input, :output, :cache_read, :cache_write, :reasoning, :cost
+    :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, cost: 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),
-        cost: number(cost, :cost, integer: false)
+        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
 
@@ -465,6 +501,8 @@ module AgentCliRuntime
       cache_read + cache_write
     end
 
+    alias provider_reported_cost cost
+
     private
 
     def number(value, label, integer:)
@@ -477,6 +515,14 @@ module AgentCliRuntime
 
       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

data/lib/agent_cli_runtime/version.rb

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

data/lib/agent_cli_runtime.rb

@@ -8,12 +8,14 @@ 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"
@@ -37,6 +39,10 @@ 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-cli-runtime
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.4
 platform: ruby
 authors:
 - Ivan Kuznetsov
@@ -64,11 +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, Grok CLI, and
-  OpenCode. 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:
@@ -83,9 +83,11 @@ 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
@@ -122,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: []