agent-cli-runtime 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 59030c0c124438712ef78cc86c61a0d26ce929ff424ea468493e0c899f660599
+  data.tar.gz: fe1ccdd4b7c38c75dbd5491b20eefde6d60e493e4ceec116cbc3c2181f159559
+SHA512:
+  metadata.gz: 4f794b419f2503d453e08c60e49a0c39d21eb7fd096a658fc18fd159c2b13803e5259f7c0bcb69f1033e1f964d818789db9713ada5eeaecd624710af65806506
+  data.tar.gz: 6746e8807b5da2ee77b9e48828db7cb7de5aea48553961be867143a5b09110ca59de3ff40f3a34fbaeb38df6b763d728f9727586cfd5bb2126982a6c22e85327

data/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 - 2026-07-26
+
+- Add immutable profiles for Claude Code, Codex CLI, Pi, and Grok CLI.
+- Add provider-neutral invocation compilation, local prerequisite probes,
+  capability evidence, usage extraction, and result normalization.
+- Add the `agent-runtime probe` diagnostic executable with versioned JSON and
+  stable exit statuses.
+- Keep missing provider usage unknown instead of recording fabricated zero
+  counts, and preserve typed unknown-provider errors through the public facade.
+- Harden local probing around subprocess environments, ambiguous version
+  output, TERM-resistant descendants, custom capability evidence, unused Grok
+  credential paths, and long or JSON-delimited secrets.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Kuznetsov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,156 @@
+# 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.
+
+## Install
+
+```ruby
+gem "agent-cli-runtime", "~> 0.1.0"
+```
+
+```ruby
+require "agent_cli_runtime"
+```
+
+Ruby 3.4 or newer is required. Version 0.1.x is tested on Linux and macOS.
+
+## Compile an invocation
+
+```ruby
+profile = AgentCliRuntime::Profiles.fetch(:codex)
+request = AgentCliRuntime::Request.new(
+  profile: profile,
+  prompt: "Review the current diff",
+  permission_mode: "read-only",
+  model: "gpt-5.6-terra",
+  effort: "high"
+)
+
+invocation = AgentCliRuntime.compile(request)
+invocation.argv       # frozen argv; no shell interpolation
+invocation.stdin_data # prompt text for stdin-style providers
+```
+
+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.
+
+## Public API
+
+- `compile(request)` returns a frozen argv/stdin invocation.
+- `probe(profile)` and `probe_all` report local prerequisite evidence without
+  contacting a provider.
+- `prepare!(profile)` requires that local probe to be ready.
+- `require_capability!(profile, name)` verifies a named CLI capability and
+  returns typed evidence.
+- `extract_usage(profile, event)` normalizes provider usage when present and
+  returns `nil` when usage is absent or malformed.
+- `observe(profile, result)` normalizes bounded, redacted result metadata.
+
+Provider arguments accept a built-in name or an `AgentCliRuntime::Profile`.
+Unknown built-in names raise `AgentCliRuntime::UnknownProvider`; they are not
+converted into generic probe or capability failures.
+
+## Custom profiles
+
+```ruby
+profile = AgentCliRuntime::Profile.new(
+  name: :acme,
+  bin_default: "acme-agent",
+  env_bin_override_keys: ["ACME_AGENT_BIN"],
+  headless_flag: "run",
+  version_flag: "--version",
+  min_version: "1.2.0",
+  prompt_style: :stdin,
+  read_only_flags: ["--sandbox", "read-only"],
+  cli_capabilities: {
+    safe_mode: ["--safe-mode"]
+  },
+  usage_extractor: ->(event) { event["usage"] },
+  auth_configuration_probe: ->(home:, env:) {
+    AgentCliRuntime::AuthConfiguration.new(
+      status: env["ACME_API_KEY"].to_s.empty? ? :missing : :configured,
+      source: "environment"
+    )
+  }
+)
+
+request = AgentCliRuntime::Request.new(
+  profile: profile,
+  prompt: "Inspect the project",
+  permission_mode: "read-only",
+  capabilities: [:safe_mode]
+)
+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.
+
+## Inspect local prerequisites
+
+```sh
+agent-runtime probe codex
+agent-runtime probe --all --json
+```
+
+The JSON contract is `{"schema_version":1,"probes":[...]}` and always orders
+all-provider output as `claude`, `codex`, `pi`, `grok`.
+
+- Exit `0`: every requested local probe is ready.
+- Exit `1`: at least one requested local prerequisite is unavailable.
+- Exit `64`: invalid usage.
+
+The probe observes only the local executable, version output, authentication
+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.
+
+## Development
+
+```sh
+cd components/agent-cli-runtime
+bundle exec rake test
+gem build agent-cli-runtime.gemspec
+```
+
+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.
+
+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.
+
+## 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.

data/agent-cli-runtime.gemspec

@@ -0,0 +1,48 @@
+require_relative "lib/agent_cli_runtime/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "agent-cli-runtime"
+  spec.version = AgentCliRuntime::VERSION
+  spec.authors = [ "Ivan Kuznetsov" ]
+  spec.email = [ "ivan@ikuznetsov.com" ]
+  spec.summary = "Provider-neutral contracts for installed agent CLIs"
+  spec.description = <<~DESC
+    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.
+  DESC
+  spec.homepage = "https://github.com/ivankuznetsov/hive"
+  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",
+    "changelog_uri" =>
+      "https://github.com/ivankuznetsov/hive/blob/main/components/agent-cli-runtime/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",
+    "rubygems_mfa_required" => "true"
+  }
+
+  spec.files = Dir.chdir(__dir__) do
+    Dir[
+      "lib/**/*.rb",
+      "exe/agent-runtime",
+      "README.md",
+      "CHANGELOG.md",
+      "LICENSE.txt",
+      "agent-cli-runtime.gemspec"
+    ]
+  end
+  spec.bindir = "exe"
+  spec.executables = [ "agent-runtime" ]
+  spec.require_paths = [ "lib" ]
+
+  spec.add_dependency "json", ">= 2.7", "< 3.0"
+  spec.add_dependency "open3", "~> 0.2"
+  spec.add_dependency "timeout", ">= 0.4", "< 1.0"
+end

data/exe/agent-runtime

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "agent_cli_runtime"
+
+exit AgentCliRuntime::CLI.run(ARGV)

data/lib/agent_cli_runtime/cli.rb

@@ -0,0 +1,98 @@
+require "json"
+
+module AgentCliRuntime
+  class CLI
+    USAGE = <<~TEXT.freeze
+      Usage:
+        agent-runtime probe PROVIDER [--json]
+        agent-runtime probe --all [--json]
+        agent-runtime --version
+
+      Providers: #{Profiles.names.join(', ')}
+    TEXT
+
+    class << self
+      def run(argv, out: $stdout, err: $stderr, home: nil, env: ENV)
+        arguments = argv.dup
+        if arguments == [ "--version" ]
+          out.puts VERSION
+          return 0
+        end
+        return usage_error(err) unless arguments.shift == "probe"
+
+        json = arguments.delete("--json")
+        all = arguments.delete("--all")
+        return usage_error(err) if arguments.any? { |arg| arg.start_with?("-") }
+        return usage_error(err) if all && !arguments.empty?
+        return usage_error(err) unless all || arguments.length == 1
+
+        results =
+          if all
+            Probe.all(home: home, env: env)
+          else
+            [ Probe.call(Profiles.fetch(arguments.fetch(0)), home: home, env: env) ]
+          end
+        json ? render_json(results, out) : render_text(results, out)
+        results.all?(&:ready) ? 0 : 1
+      rescue UnknownProvider => e
+        err.puts e.message
+        err.print USAGE
+        64
+      end
+
+      private
+
+      def usage_error(err)
+        err.print USAGE
+        64
+      end
+
+      def render_json(results, out)
+        payload = {
+          schema_version: 1,
+          probes: results.map { |result| probe_hash(result) }
+        }
+        out.puts JSON.generate(payload)
+      end
+
+      def render_text(results, out)
+        results.each do |result|
+          state = result.ready ? "ready" : "unavailable"
+          version = result.version || "unknown"
+          auth = result.auth_configuration.status
+          out.puts(
+            "#{result.provider}: #{state} " \
+            "(installed=#{result.installed} version=#{version} " \
+            "auth_configuration=#{auth})"
+          )
+          out.puts "  #{result.diagnostic}" if result.diagnostic
+        end
+      end
+
+      def probe_hash(result)
+        {
+          provider: result.provider.to_s,
+          ready: result.ready,
+          installed: result.installed,
+          executable: Redactor.diagnostic(result.executable, bytes: 256),
+          version: result.version,
+          minimum_version: result.minimum_version,
+          auth_configuration: {
+            status: result.auth_configuration.status.to_s,
+            source: Redactor.diagnostic(
+              result.auth_configuration.source,
+              bytes: 256
+            )
+          },
+          capabilities: result.capability_evidence.map do |evidence|
+            {
+              capability: evidence.capability.to_s,
+              supported: evidence.supported
+            }
+          end,
+          diagnostic: result.diagnostic
+        }
+      end
+    end
+  end
+end

data/lib/agent_cli_runtime/errors.rb

@@ -0,0 +1,17 @@
+module AgentCliRuntime
+  class Error < StandardError
+    attr_reader :evidence
+
+    def initialize(message, evidence: nil)
+      super(message)
+      @evidence = evidence
+    end
+  end
+
+  class BinaryUnavailable < Error; end
+  class VersionError < Error; end
+  class UnsupportedCapability < Error; end
+  class ProbeError < Error; end
+  class CompilationError < Error; end
+  class UnknownProvider < Error; end
+end

data/lib/agent_cli_runtime/probe.rb

@@ -0,0 +1,91 @@
+module AgentCliRuntime
+  module Probe
+    module_function
+
+    def call(profile, home: nil, env: ENV)
+      resolved = Profiles.resolve(profile)
+      executable = resolved.bin(env:)
+      installed = resolved.binary_installed?(env:)
+      version = nil
+      diagnostic = nil
+
+      if installed
+        begin
+          version = resolved.check_version!(env:)
+        rescue Error => e
+          diagnostic = Redactor.diagnostic(e)
+        end
+      else
+        diagnostic = Redactor.diagnostic(
+          "#{resolved.name} binary not runnable: #{executable}"
+        )
+      end
+
+      auth =
+        if installed
+          resolved.auth_configuration(home: home, env: env)
+        else
+          AuthConfiguration.new(status: :not_checked)
+        end
+      diagnostic ||= auth.diagnostic
+      ready = installed &&
+              !version.nil? &&
+              auth.status != :missing
+
+      ProbeResult.new(
+        provider: resolved.name,
+        ready: ready,
+        installed: installed,
+        executable: executable,
+        version: version,
+        minimum_version: resolved.min_version,
+        auth_configuration: auth,
+        capability_evidence: capability_evidence(
+          resolved, installed: installed, version: version, auth: auth
+        ),
+        diagnostic: diagnostic
+      )
+    rescue StandardError => e
+      resolved ||= Profiles.resolve(profile)
+      ProbeResult.new(
+        provider: resolved.name,
+        ready: false,
+        installed: false,
+        executable: resolved.bin(env:),
+        version: nil,
+        minimum_version: resolved.min_version,
+        auth_configuration: AuthConfiguration.new(status: :not_checked),
+        capability_evidence: [],
+        diagnostic: Redactor.diagnostic(e)
+      )
+    end
+
+    def all(home: nil, env: ENV)
+      Profiles.names.map do |provider|
+        call(provider, home: home, env: env)
+      end.freeze
+    end
+
+    def capability_evidence(profile, installed:, version:, auth:)
+      declared = profile.declared_capability_support
+      capabilities = {
+        headless: declared.fetch(:headless),
+        version: !version.nil?,
+        auth_configuration: auth.status != :missing
+      }
+      declared.each do |capability, supported|
+        capabilities[capability] = supported unless capability == :headless
+      end
+      capabilities[:installation] = installed
+      capabilities.map do |capability, supported|
+        CapabilityEvidence.new(
+          capability: capability,
+          supported: supported,
+          provider: profile.name,
+          launcher_identity: profile.launcher_identity
+        )
+      end.freeze
+    end
+    private_class_method :capability_evidence
+  end
+end