agent-cli-runtime 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59030c0c124438712ef78cc86c61a0d26ce929ff424ea468493e0c899f660599
-  data.tar.gz: fe1ccdd4b7c38c75dbd5491b20eefde6d60e493e4ceec116cbc3c2181f159559
+  metadata.gz: 38323f74e355a6a9da1dfb45ccee48c253ffbd0c9693a16cd62910ced381c7cb
+  data.tar.gz: 2e38766e9b737df1e5360ac8013849cf2108dab3f8b937f24ec393c001aba669
 SHA512:
-  metadata.gz: 4f794b419f2503d453e08c60e49a0c39d21eb7fd096a658fc18fd159c2b13803e5259f7c0bcb69f1033e1f964d818789db9713ada5eeaecd624710af65806506
-  data.tar.gz: 6746e8807b5da2ee77b9e48828db7cb7de5aea48553961be867143a5b09110ca59de3ff40f3a34fbaeb38df6b763d728f9727586cfd5bb2126982a6c22e85327
+  metadata.gz: 95e1213e6586ea162e2a12294b350d4ea5190c8f09239e276fe4de17ceb1a7787c0c4979e3e71c6acb0f8e318facea099820a221130b123549d8a123c13e62b7
+  data.tar.gz: 1cca33e3af240a7abf5b8627d69256ee43647557fc2aeeab4f74692c7ba08ff74a0b0a5cdef202796f4559cc04d0498138762003fd14845c61029bd0b7603231

data/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.0 - 2026-08-15
+
+- Add OpenCode `1.18.16+` as a fifth immutable built-in profile with exact
+  `provider/model` routing and faithful model-variant validation.
+- Add route-aware offline probing for the required run/export flags, selected
+  authentication source, cached model inventory, and exact requested route.
+- Add invocation-owned OpenCode config/data/cache/state overlays with
+  deny-first `read-only` and `workspace-write` policies, explicit credential
+  forwarding, owner-private resources, and idempotent cleanup.
+- Add strict run/export correlation and typed outcomes for completion,
+  authentication/configuration/CLI failure, malformed output, cancellation,
+  and timeout while preserving requested versus actual route identity.
+- Preserve unavailable separately from numeric zero for input, output,
+  cache-read, cache-write, reasoning, and cost evidence.
+- Keep process spawning, streaming, timeout/cancellation supervision,
+  process-tree cleanup, retries, and post-run inspection execution with the
+  caller; the component returns commands and normalizes captured evidence.
+
+## 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,25 +1,24 @@
 # 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, Grok CLI, and OpenCode 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. OpenCode adds an invocation-owned overlay and strict captured-result
+normalizer while leaving process supervision with the caller.
 
 ## Install
 
 ```ruby
-gem "agent-cli-runtime", "~> 0.1.0"
+gem "agent-cli-runtime", "~> 0.2.0"
 ```
 
 ```ruby
 require "agent_cli_runtime"
 ```
 
-Ruby 3.4 or newer is required. Version 0.1.x is tested on Linux and macOS.
+Ruby 3.4 or newer is required. The 0.2.x line is tested on Linux and macOS.
 
 ## Compile an invocation
 
@@ -42,11 +41,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
 
@@ -59,6 +58,14 @@ enforce a mode its CLI cannot represent.
 - `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.
+- `prepare!(open_code_preparation)` creates and probes an isolated OpenCode
+  overlay and returns a `PreparedInvocation`; it does not spawn OpenCode.
+- `parse_run(profile, stdout:)` parses a successful OpenCode JSONL capture
+  into the session and terminal-message identity required for inspection.
+- `prepare_inspection(prepared, parsed_run)` compiles the non-model sanitized
+  session-export command without executing it.
+- `normalize(profile, captured, requested_route:)` returns one typed OpenCode
+  outcome from caller-captured run, termination, and inspection evidence.
 
 Provider arguments accept a built-in name or an `AgentCliRuntime::Profile`.
 Unknown built-in names raise `AgentCliRuntime::UnknownProvider`; they are not
@@ -76,6 +83,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,16 +110,155 @@ 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.
+
+## Prepare and normalize OpenCode
+
+OpenCode `1.18.16+` requires an exact `provider/model` route and an explicit,
+read-only configuration source. Configuration may define providers and an
+exact default model, but it must not contain credential values. Name the
+credential environment variables the caller is allowed to forward instead.
+
+```ruby
+require "agent_cli_runtime"
+require "tmpdir"
+
+route = "anthropic/claude-sonnet-4-5"
+profile = AgentCliRuntime::Profiles.fetch(:opencode)
+request = AgentCliRuntime::Request.new(
+  profile: profile,
+  prompt: "Make the requested atomic edit",
+  permission_mode: "workspace-write",
+  model: route,
+  effort: "high"
+)
+preparation = AgentCliRuntime::OpenCodePreparationRequest.new(
+  request: request,
+  working_directory: Dir.pwd,
+  invocation_root: File.join(Dir.tmpdir, "my-opencode-invocation"),
+  configuration: {
+    "model" => route,
+    "provider" => {
+      "anthropic" => { "npm" => "@ai-sdk/anthropic" }
+    }
+  },
+  credential_environment_keys: ["ANTHROPIC_API_KEY"],
+  additional_read_roots: [Dir.pwd],
+  additional_write_roots: [Dir.pwd]
+)
+
+prepared = AgentCliRuntime.prepare!(preparation)
+begin
+  # The caller owns spawning, capture, timeout/cancellation, and process-tree
+  # cleanup. Forward only this selected environment to the child.
+  run_argv = prepared.invocation.argv
+  run_stdin = prepared.invocation.stdin_data
+  run_environment = prepared.environment_for(env: ENV)
+
+  # After a zero main-process exit, parse the captured JSONL and run the
+  # separately compiled, non-model sanitized export under the same overlay.
+  parsed = AgentCliRuntime.parse_run(:opencode, stdout: run_stdout)
+  inspection = AgentCliRuntime.prepare_inspection(prepared, parsed)
+  inspection_argv = inspection.argv
+  inspection_environment = inspection.environment_for(env: ENV)
+
+  captured = AgentCliRuntime::CapturedResult.new(
+    stdout: run_stdout,
+    stderr: run_stderr,
+    termination: AgentCliRuntime::TerminationEvidence.new(exit_code: 0),
+    inspection_output: sanitized_export_stdout
+  )
+  outcome = AgentCliRuntime.normalize(
+    :opencode, captured, requested_route: prepared.requested_route
+  )
+ensure
+  prepared.cleanup! if prepared
+end
+```
+
+`run_stdout`, `run_stderr`, and `sanitized_export_stdout` above are captures
+provided by the caller's process supervisor. Execute the inspection only after
+a successful main run. For a timeout, cancellation, signal, or non-zero exit,
+construct the matching `TerminationEvidence` and normalize without pretending
+that incomplete output is a successful result.
+
+Preparation creates owner-private config, data, cache, and state paths below
+the fresh invocation root; redirects OpenCode into them; disables ambient
+project/default discovery and remote model refresh; checks version, required
+flags, selected auth, cached route, and requested variant locally; and returns
+discrete argv/environment values. It never sends a prompt or model request.
+`PreparedInvocation#cleanup!` removes only invocation-owned paths and is safe
+to call twice. Call it from the process owner's `ensure` path after every
+pre-spawn and post-spawn outcome.
+
+`read-only` denies edits, shell, unsafe tools, and external writes.
+`workspace-write` permits edits only under the declared write roots and still
+denies unrestricted shell. A `nil` permission mode is rejected unless the
+consumer supplies an explicit typed `OpenCodePermissionPolicy`; the ordinary
+preparation API never silently falls back to a bypass. Plugin sources are
+explicit, and `--pure` remains enabled when no plugin was selected.
+
+A completed outcome contains one bounded final assistant message, requested
+and sanitized-export-observed routes, and nullable input/output/cache
+read/cache write/reasoning/cost fields. Missing evidence stays `nil`; numeric
+zero stays zero. Other outcome kinds are `authentication_failure`,
+`configuration_failure`, `cli_failure`, `malformed_output`, `cancelled`, and
+`timed_out`. Diagnostics and unknown-event summaries are bounded and redacted.
+
+Maintainers can run the installed-CLI offline contract without a prompt or
+model request:
+
+```sh
+bundle exec ruby -Itest test/opencode_offline_smoke_test.rb
+```
+
+If an installation command is itself a package-manager shim, set
+`AGENT_CLI_RUNTIME_OPENCODE_OFFLINE_BIN` to the already-installed native
+OpenCode executable so the smoke cannot trigger shim installation or refresh
+behavior.
+
+The authenticated atomic-edit smoke is separately gated and refuses to run
+without an explicit route, config path, credential variable name, opt-in, and
+non-empty selected credential:
+
+```sh
+AGENT_CLI_RUNTIME_OPENCODE_LIVE=1 \
+AGENT_CLI_RUNTIME_OPENCODE_LIVE_ROUTE=anthropic/claude-sonnet-4-5 \
+AGENT_CLI_RUNTIME_OPENCODE_LIVE_CONFIG=/absolute/path/opencode.json \
+AGENT_CLI_RUNTIME_OPENCODE_LIVE_CREDENTIAL_ENV=ANTHROPIC_API_KEY \
+ANTHROPIC_API_KEY=... \
+bundle exec ruby -Itest test/opencode_live_test.rb
+```
+
+The live test records only route, CLI version, outcome/usage availability, and
+cleanup state. It does not print the credential or raw selected config. A
+missing opt-in input is an explicit skip, not a deterministic-suite failure.
 
 ## 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
 ```
 
 The JSON contract is `{"schema_version":1,"probes":[...]}` and always orders
-all-provider output as `claude`, `codex`, `pi`, `grok`.
+all-provider output as `claude`, `codex`, `pi`, `grok`, `opencode`.
 
 - Exit `0`: every requested local probe is ready.
 - Exit `1`: at least one requested local prerequisite is unavailable.
@@ -120,37 +269,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
+## Normalize provider output
 
-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
+```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.2.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

@@ -9,22 +9,22 @@ Gem::Specification.new do |spec|
   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.
+    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.
   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/errors.rb

@@ -14,4 +14,11 @@ module AgentCliRuntime
   class ProbeError < Error; end
   class CompilationError < Error; end
   class UnknownProvider < Error; end
+  class PreparationError < Error; end
+  class ConfigurationError < PreparationError; end
+  class AuthenticationError < ProbeError; end
+  class RouteUnavailable < ProbeError; end
+  class UnsafePathError < PreparationError; end
+  class ResultError < Error; end
+  class MalformedOutput < ResultError; end
 end

data/lib/agent_cli_runtime/opencode/inspection.rb

@@ -0,0 +1,32 @@
+module AgentCliRuntime
+  module OpenCode
+    module Inspection
+      module_function
+
+      def compile(prepared, parsed_run)
+        unless prepared.is_a?(PreparedInvocation)
+          raise ArgumentError,
+                "prepared must be an AgentCliRuntime::PreparedInvocation"
+        end
+        unless parsed_run.is_a?(ParsedRun)
+          raise ArgumentError, "parsed_run must be an AgentCliRuntime::ParsedRun"
+        end
+        unless prepared.invocation.provider == :opencode
+          raise ConfigurationError,
+                "sanitized export inspection requires an OpenCode invocation"
+        end
+
+        InspectionCommand.new(
+          argv: [
+            prepared.executable, "export", parsed_run.session_id, "--sanitize"
+          ],
+          stdin_data: nil,
+          environment: prepared.environment,
+          credential_environment_keys: prepared.credential_environment_keys,
+          session_id: parsed_run.session_id,
+          message_id: parsed_run.terminal_message_id
+        )
+      end
+    end
+  end
+end