agent-cli-runtime 0.1.1 → 0.2.4

data/lib/agent_cli_runtime/profiles.rb

@@ -103,11 +103,44 @@ 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",
       env_bin_override_keys: %w[AGENT_CLI_RUNTIME_CLAUDE_BIN HIVE_CLAUDE_BIN],
       headless_flag: "-p",
+      # Print mode reads stdin; keep large review prompts out of exec arguments.
+      prompt_style: :piped_stdin,
       permission_skip_flag: "--dangerously-skip-permissions",
       add_dir_flag: "--add-dir",
       tool_scope_flags: {
@@ -125,6 +158,7 @@ module AgentCliRuntime
       effort_argument_builder: ->(effort) { [ "--effort", effort ] },
       launcher_identity: "claude-code/v1",
       usage_extractor: UsageExtractors::CLAUDE,
+      error_extractor: ErrorExtractors::CLAUDE,
       credential_environment_keys: %w[
         ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN CLAUDE_API_KEY
       ],
@@ -189,12 +223,17 @@ module AgentCliRuntime
       bin_default: "pi",
       env_bin_override_keys: %w[AGENT_CLI_RUNTIME_PI_BIN HIVE_PI_BIN],
       headless_flag: "-p",
+      # Pi reads a non-TTY stdin stream into its initial message without an
+      # argv placeholder. Keeping the prompt out of argv also avoids Linux's
+      # per-argument size limit on real implementation plans.
+      prompt_style: :piped_stdin,
       output_format_flags: [ "--mode", "json", "--no-session" ],
       version_flag: "--version",
       min_version: "0.70.2",
       model_argument_builder: ->(model) { [ "--model", model ] },
       launcher_identity: "pi-coding-agent/v1",
       usage_extractor: UsageExtractors::PI,
+      error_extractor: ErrorExtractors::PI,
       credential_environment_keys: PI_CREDENTIAL_ENVIRONMENT_KEYS,
       configuration_environment_key: "PI_CODING_AGENT_DIR",
       default_configuration_directory: ".pi/agent",
@@ -216,9 +255,18 @@ module AgentCliRuntime
       name: :grok,
       bin_default: "grok",
       env_bin_override_keys: %w[AGENT_CLI_RUNTIME_GROK_BIN HIVE_GROK_BIN],
-      headless_flag: "-p",
-      prompt_style: :headless_flag_value,
+      # Grok's Unix CLI reads a prompt file; stdin already has a managed lifetime.
+      headless_flag: "--prompt-file=/dev/stdin",
+      prompt_style: :piped_stdin,
       permission_skip_flag: "--always-approve",
+      # Grok confines the filesystem natively, the same shape codex uses.
+      # `workspace` limits writes to the working directory, `read-only`
+      # forbids them entirely; both are built-in profiles (custom ones extend
+      # them from ~/.grok/sandbox.toml). `--always-approve` suppresses the
+      # interactive approval prompt, which a headless reviewer can never answer
+      # — the sandbox, not the prompt, is what actually bounds the agent.
+      workspace_write_flags: [ "--sandbox", "workspace", "--always-approve" ],
+      read_only_flags: [ "--sandbox", "read-only", "--always-approve" ],
       output_format_flags: [ "--output-format", "streaming-json" ],
       version_flag: "--version",
       min_version: "0.2.90",
@@ -242,7 +290,54 @@ 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",
+      # `opencode run` reads a non-TTY stdin stream as the initial message.
+      # Keep implementation-sized prompts out of one argv element: Linux
+      # rejects a single argument around 128 KiB with E2BIG even when the
+      # complete argv remains far below ARG_MAX.
+      prompt_style: :piped_stdin,
+      # Bun-backed OpenCode startup can exceed the generic 10-second bound
+      # under sustained host I/O even though the executable is healthy.
+      version_check_timeout_sec: 30,
+      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,
+      error_extractor: ErrorExtractors::OPENCODE,
+      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

@@ -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
@@ -63,9 +74,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(
@@ -103,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 : {}
@@ -121,6 +181,16 @@ module AgentCliRuntime
       )
     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
+
     def supported_evidence(profile, capability, arguments = [])
       CapabilityEvidence.new(
         capability: capability,
@@ -253,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)