agent-cli-runtime 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59315cc0411f928db6beb1ecea2a7f96986c26e7436ea60d14d105c7b0252c71
-  data.tar.gz: 073dfc6f68dabb86a4307a6dbf0a61a3238f6dea32256ac04432d174ea8acf6f
+  metadata.gz: 38323f74e355a6a9da1dfb45ccee48c253ffbd0c9693a16cd62910ced381c7cb
+  data.tar.gz: 2e38766e9b737df1e5360ac8013849cf2108dab3f8b937f24ec393c001aba669
 SHA512:
-  metadata.gz: abca7ef13599eae3e161b085ee97e334a3a665fd9a8de01ae0bbb3719cb9034edda857e6ad12c188936cd3b2e696811488b28505c6aa8edf6cff25aabda02959
-  data.tar.gz: e8d831b5884967165f4422472b6bce5510f76fd581173955536eadd871e851358f3017a851865cc64530b0ffa42b47c8bfe5549d709978e8ef6a54b270a2f30b
+  metadata.gz: 95e1213e6586ea162e2a12294b350d4ea5190c8f09239e276fe4de17ceb1a7787c0c4979e3e71c6acb0f8e318facea099820a221130b123549d8a123c13e62b7
+  data.tar.gz: 1cca33e3af240a7abf5b8627d69256ee43647557fc2aeeab4f74692c7ba08ff74a0b0a5cdef202796f4559cc04d0498138762003fd14845c61029bd0b7603231

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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

data/README.md

@@ -2,21 +2,23 @@
 
 `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.
+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
 
@@ -56,6 +58,14 @@ 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
@@ -108,6 +118,128 @@ 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
@@ -126,7 +258,7 @@ 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.
@@ -172,7 +304,7 @@ own provider-health policy.
 ## Compatibility
 
 Provider flags, event formats, and public value-object fields are
-SemVer-governed behavior. Additive fields are compatible within 0.1.x; removing
+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.
 

data/agent-cli-runtime.gemspec

@@ -9,8 +9,9 @@ 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/agent-cli-runtime"
   spec.license = "MIT"

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