agent-cli-runtime 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59030c0c124438712ef78cc86c61a0d26ce929ff424ea468493e0c899f660599
-  data.tar.gz: fe1ccdd4b7c38c75dbd5491b20eefde6d60e493e4ceec116cbc3c2181f159559
+  metadata.gz: 59315cc0411f928db6beb1ecea2a7f96986c26e7436ea60d14d105c7b0252c71
+  data.tar.gz: 073dfc6f68dabb86a4307a6dbf0a61a3238f6dea32256ac04432d174ea8acf6f
 SHA512:
-  metadata.gz: 4f794b419f2503d453e08c60e49a0c39d21eb7fd096a658fc18fd159c2b13803e5259f7c0bcb69f1033e1f964d818789db9713ada5eeaecd624710af65806506
-  data.tar.gz: 6746e8807b5da2ee77b9e48828db7cb7de5aea48553961be867143a5b09110ca59de3ff40f3a34fbaeb38df6b763d728f9727586cfd5bb2126982a6c22e85327
+  metadata.gz: abca7ef13599eae3e161b085ee97e334a3a665fd9a8de01ae0bbb3719cb9034edda857e6ad12c188936cd3b2e696811488b28505c6aa8edf6cff25aabda02959
+  data.tar.gz: e8d831b5884967165f4422472b6bce5510f76fd581173955536eadd871e851358f3017a851865cc64530b0ffa42b47c8bfe5549d709978e8ef6a54b270a2f30b

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.1.1 - 2026-08-11
+
+- Expose each profile's immutable credential-environment key inventory so
+  orchestrators can isolate named subscription/session bindings without
+  embedding provider-specific compatibility tables.
+- Expose each profile's configuration-directory override and home-relative
+  default so orchestrators can detect subscription-session aliases without
+  maintaining a second provider-specific table.
+- Include Claude's ambient auth-token override in the isolation inventory so a
+  named subscription binding cannot be silently replaced by caller state.
+- Preserve an optional immutable provider signal in observable results so a
+  trusted orchestrator can carry structured transport evidence without moving
+  provider-health classification into the compatibility package.
+
 ## 0.1.0 - 2026-07-26
 
 - Add immutable profiles for Claude Code, Codex CLI, Pi, and Grok CLI.

data/README.md

@@ -1,13 +1,10 @@
 # Agent CLI Runtime
 
-`agent-cli-runtime` is a small Ruby library for tools that need to describe
-and inspect locally installed headless agent CLIs without owning an agent
-orchestration system.
-
-It ships immutable profiles for Claude Code, Codex CLI, Pi, and Grok CLI;
-compiles provider-neutral requests into argv/stdin; reports typed capability
-evidence; extracts usage from provider JSON events; and exposes an honest local
-diagnostic command.
+`agent-cli-runtime` is a small Ruby library for tools that integrate with
+locally installed headless agent CLIs. It ships immutable profiles for Claude
+Code, Codex CLI, Pi, and Grok CLI and compiles provider-neutral requests into
+argv/stdin. It also reports typed capability evidence, extracts usage from
+provider JSON events, and exposes an honest local diagnostic command.
 
 ## Install
 
@@ -42,11 +39,11 @@ Compilation does not execute the returned command. Unsupported requested
 controls raise `AgentCliRuntime::UnsupportedCapability` with typed evidence
 instead of silently widening the request.
 
-`permission_mode: nil` deliberately preserves Hive's existing trusted,
-headless behavior: providers with a bypass flag receive that flag. Consumers
-that do not want this compatibility path should pass `"read-only"` or
-`"workspace-write"` explicitly. A profile raises instead of pretending to
-enforce a mode its CLI cannot represent.
+`permission_mode: nil` selects the profile's default non-interactive permission
+flags, which may include a provider's bypass flag. Pass `"read-only"` or
+`"workspace-write"` explicitly when the integration requires that constraint.
+A profile raises instead of pretending to enforce a mode its CLI cannot
+represent.
 
 ## Public API
 
@@ -76,6 +73,9 @@ profile = AgentCliRuntime::Profile.new(
   min_version: "1.2.0",
   prompt_style: :stdin,
   read_only_flags: ["--sandbox", "read-only"],
+  credential_environment_keys: ["ACME_API_KEY", "ACME_OAUTH_TOKEN"],
+  configuration_environment_key: "ACME_HOME",
+  default_configuration_directory: ".acme",
   cli_capabilities: {
     safe_mode: ["--safe-mode"]
   },
@@ -100,9 +100,26 @@ AgentCliRuntime.compile(request)
 Custom capability names cannot shadow the standard capability vocabulary.
 Capability checks use discrete argv, inspect the installed CLI's help, and
 fail closed when a declared option is not advertised.
+`credential_environment_keys` is an immutable compatibility inventory for
+orchestrators that isolate a named CLI session; it contains variable names,
+never their values.
+`configuration_environment_key` and `default_configuration_directory` describe
+where the CLI owns its subscription/session state. `configuration_directory`
+resolves that location from a caller-supplied home and environment without
+reading credentials or deciding authentication policy.
 
 ## Inspect local prerequisites
 
+```ruby
+probe = AgentCliRuntime.probe(:codex)
+probe.ready
+probe.version
+probe.auth_configuration.status
+
+# Returns the ready probe or raises AgentCliRuntime::ProbeError.
+AgentCliRuntime.prepare!(:codex)
+```
+
 ```sh
 agent-runtime probe codex
 agent-runtime probe --all --json
@@ -120,37 +137,48 @@ configuration presence, and declared capabilities. `configured` means a
 recognized local file or environment variable is present. It does not mean the
 credential is valid, the provider is online, or the account has quota.
 
-## Scope and compatibility
-
-The library does not spawn or supervise agents, retry work, run workflows,
-accept artifacts, or interpret Hive state. Provider flags and event formats are
-SemVer-governed public behavior. Additive fields are compatible within 0.1.x;
-removing or changing an existing field or meaning requires a new minor version
-while the gem remains pre-1.0.
-
-Development remains in the Hive monorepo under
-`components/agent-cli-runtime`. Hive is the primary consumer and HiveBench is
-the first named external adopter. The Hive maintainer team owns compatibility,
-security response, and releases for the package.
+## Normalize provider output
 
-## Development
-
-```sh
-cd components/agent-cli-runtime
-bundle exec rake test
-gem build agent-cli-runtime.gemspec
+```ruby
+usage = AgentCliRuntime.extract_usage(
+  :codex,
+  "type" => "turn.completed",
+  "usage" => {
+    "input_tokens" => 120,
+    "output_tokens" => 42
+  }
+)
+# => { input: 120, output: 42, cached: 0, model: nil }
+
+result = AgentCliRuntime.observe(
+  :codex,
+  exit_code: 0,
+  timed_out: false,
+  status: :completed,
+  usage: usage,
+  final_message: "Review complete"
+)
+result.status # => :completed
+result.usage  # => the normalized usage hash
 ```
 
-The root suite includes these package tests plus Hive/package parity coverage;
-run `bundle exec rake test:agent_cli_runtime` from the repository root for the
-standalone component gate alone.
+Malformed or unrelated events return `nil` from `extract_usage`; they do not
+invent zero-token usage. `observe` returns a frozen
+`AgentCliRuntime::ObservableResult` with bounded, redacted diagnostics. A
+trusted caller may also supply an already-normalized `provider_signal`; the
+runtime carries that optional immutable value but does not classify failures or
+own provider-health policy.
+
+## Compatibility
 
-Release instructions live in the repository's `docs/RELEASING.md`. Releases
-use component-scoped tags and publish exact preverified gem bytes through
-RubyGems trusted publishing.
+Provider flags, event formats, and public value-object fields are
+SemVer-governed behavior. Additive fields are compatible within 0.1.x; removing
+or changing an existing field or meaning requires a new minor version while the
+gem remains pre-1.0.
 
 ## Security
 
 Diagnostics are bounded and redact common credential forms. The library never
 prints credential file contents or environment values. Report vulnerabilities
-through the Hive repository’s security policy.
+privately through the
+[package security policy](https://github.com/ivankuznetsov/agent-cli-runtime/security/policy).

data/agent-cli-runtime.gemspec

@@ -12,19 +12,18 @@ Gem::Specification.new do |spec|
     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.
   DESC
-  spec.homepage = "https://github.com/ivankuznetsov/hive"
+  spec.homepage = "https://github.com/ivankuznetsov/agent-cli-runtime"
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.4.0"
 
   spec.metadata = {
     "homepage_uri" => spec.homepage,
-    "source_code_uri" =>
-      "https://github.com/ivankuznetsov/hive/tree/main/components/agent-cli-runtime",
+    "source_code_uri" => spec.homepage,
     "changelog_uri" =>
-      "https://github.com/ivankuznetsov/hive/blob/main/components/agent-cli-runtime/CHANGELOG.md",
+      "#{spec.homepage}/blob/main/CHANGELOG.md",
     "bug_tracker_uri" => "https://github.com/ivankuznetsov/hive/issues",
     "documentation_uri" =>
-      "https://github.com/ivankuznetsov/hive/blob/main/components/agent-cli-runtime/README.md",
+      "#{spec.homepage}/blob/main/README.md",
     "rubygems_mfa_required" => "true"
   }
 

data/lib/agent_cli_runtime/profile.rb

@@ -25,7 +25,9 @@ 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
 
     def initialize(name:, bin_default:, headless_flag:, version_flag:,
                    env_bin_override_keys: [], permission_skip_flag: nil,
@@ -35,7 +37,9 @@ 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)
       normalized_prompt_style = prompt_style.to_sym
       unless PROMPT_STYLES.include?(normalized_prompt_style)
         raise ArgumentError,
@@ -65,6 +69,15 @@ 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
+      )
       @declared_capability_support = build_declared_capability_support
       freeze
     end
@@ -200,6 +213,24 @@ module AgentCliRuntime
       nil
     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]
@@ -229,6 +260,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
@@ -78,6 +125,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 +169,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 +195,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 +227,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")

data/lib/agent_cli_runtime/runtime.rb

@@ -116,7 +116,8 @@ module AgentCliRuntime
         final_message: raw[:final_message],
         diagnostic: Redactor.diagnostic(
           raw[:error_message] || raw[:limit_text]
-        )
+        ),
+        provider_signal: raw[:provider_signal]
       )
     end
 

data/lib/agent_cli_runtime/values.rb

@@ -154,10 +154,11 @@ module AgentCliRuntime
 
   ObservableResult = Data.define(
     :provider, :launcher_identity, :exit_code, :timed_out, :status,
-    :usage, :final_message, :diagnostic
+    :usage, :final_message, :diagnostic, :provider_signal
   ) do
     def initialize(provider:, launcher_identity:, exit_code:, timed_out:,
-                   status:, usage:, final_message:, diagnostic:)
+                   status:, usage:, final_message:, diagnostic:,
+                   provider_signal: nil)
       super(
         provider: provider.to_sym,
         launcher_identity: Immutable.string(launcher_identity),
@@ -167,7 +168,8 @@ module AgentCliRuntime
         usage: usage&.dup&.freeze,
         final_message:
           final_message.nil? ? nil : Immutable.string(final_message),
-        diagnostic: diagnostic.nil? ? nil : Immutable.string(diagnostic)
+        diagnostic: diagnostic.nil? ? nil : Immutable.string(diagnostic),
+        provider_signal: provider_signal&.dup&.freeze
       )
     end
   end

data/lib/agent_cli_runtime/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-cli-runtime
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Ivan Kuznetsov
@@ -91,15 +91,15 @@ files:
 - lib/agent_cli_runtime/usage_extractors.rb
 - lib/agent_cli_runtime/values.rb
 - lib/agent_cli_runtime/version.rb
-homepage: https://github.com/ivankuznetsov/hive
+homepage: https://github.com/ivankuznetsov/agent-cli-runtime
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/ivankuznetsov/hive
-  source_code_uri: https://github.com/ivankuznetsov/hive/tree/main/components/agent-cli-runtime
-  changelog_uri: https://github.com/ivankuznetsov/hive/blob/main/components/agent-cli-runtime/CHANGELOG.md
+  homepage_uri: https://github.com/ivankuznetsov/agent-cli-runtime
+  source_code_uri: https://github.com/ivankuznetsov/agent-cli-runtime
+  changelog_uri: https://github.com/ivankuznetsov/agent-cli-runtime/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/ivankuznetsov/hive/issues
-  documentation_uri: https://github.com/ivankuznetsov/hive/blob/main/components/agent-cli-runtime/README.md
+  documentation_uri: https://github.com/ivankuznetsov/agent-cli-runtime/blob/main/README.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: