agent-cli-runtime 0.1.1 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59315cc0411f928db6beb1ecea2a7f96986c26e7436ea60d14d105c7b0252c71
-  data.tar.gz: 073dfc6f68dabb86a4307a6dbf0a61a3238f6dea32256ac04432d174ea8acf6f
+  metadata.gz: e0202bb311856ad96fcd486517d11cfc7175db0102a188920c4d851bf338b7d6
+  data.tar.gz: 2e72a23b5e7a021fc439a9ce8ef34bf166c0af0141de491a27686d6f3ba3f139
 SHA512:
-  metadata.gz: abca7ef13599eae3e161b085ee97e334a3a665fd9a8de01ae0bbb3719cb9034edda857e6ad12c188936cd3b2e696811488b28505c6aa8edf6cff25aabda02959
-  data.tar.gz: e8d831b5884967165f4422472b6bce5510f76fd581173955536eadd871e851358f3017a851865cc64530b0ffa42b47c8bfe5549d709978e8ef6a54b270a2f30b
+  metadata.gz: b3736f38aa29d809028b1e99c9df1dd17ddb4a210382e89f752def380e84cf22e3f144da2d10ee6c86c2dab8496865a35347196277367a0734b9c39991c33f0e
+  data.tar.gz: 5adacccc362958a8cc9a2eeab22b9100041101de4795d7f31ddaa563406ec031f6b3662e84eca058b144ab86ee41d1505c42baa267c1eae436cda4566680b100

data/CHANGELOG.md

@@ -1,5 +1,92 @@
 # Changelog
 
+## Unreleased
+
+## 0.2.4 - 2026-08-25
+
+- Expose the OpenCode permission compiler independently from the prepared
+  overlay so callers can supply the same deny-first rules through native
+  per-process configuration without duplicating policy generation.
+
+- Carry the already-resolved OpenCode executable on `ProbeRequest` (`executable:`)
+  instead of re-encoding it as the `AGENT_CLI_RUNTIME_OPENCODE_BIN` environment
+  override. The route-aware probe now resolves the executable once — honoring a
+  caller-supplied value first — and threads that single value through the
+  installation check, version check, every local inspection command, and the
+  reported result executable. `Profile#binary_installed?`,
+  `Profile#check_version!`, and `Profile#capture_local` accept an optional
+  `executable:` override; existing environment-based resolution is unchanged
+  when no explicit value is carried.
+
+## 0.2.3 - 2026-08-21
+
+- Classify extracted provider failures once at the runtime boundary as
+  `provider_limit`, `rate_limited`, `model_output_limit`, or `provider_error`.
+  HTTP 402/429 payloads are authoritative even when their provider-specific
+  wording does not match an orchestrator's legacy quota phrases.
+
+## 0.2.2 - 2026-08-18
+
+- Deliver built-in Pi prompts through its native non-TTY stdin reader instead
+  of one positional argv element. This prevents implementation-sized prompts
+  from failing at process spawn with the operating system's per-argument
+  `E2BIG` limit; Codex retains its separate stdin-plus-`-` transport.
+- Treat Pi's `stopReason: "length"` as a typed `model_output_limit` failure.
+  Pi exits zero after this provider stop even when the model exhausted its
+  output allowance before writing the requested artifact; callers can now
+  distinguish that incomplete turn from an agent that silently produced
+  0 bytes and tell operators to raise `maxTokens` or lower reasoning effort.
+- Declare Grok's filesystem sandbox flags, so a caller asking for confined
+  execution gets it instead of being told Grok cannot confine. `--sandbox
+  workspace` limits writes to the working directory and `--sandbox read-only`
+  forbids them, both built-in profiles that custom ones extend from
+  `~/.grok/sandbox.toml`; `--always-approve` suppresses the approval prompt a
+  headless run can never answer, leaving the sandbox — not the prompt — as the
+  boundary. Only the Grok profile changes.
+
+## 0.2.1 - 2026-08-17
+
+- Add per-profile provider-error extraction so a refusal a CLI reports on its
+  event stream is distinguishable from an agent that genuinely produced
+  nothing. `extract_provider_error` returns the provider, the HTTP status when
+  the provider supplied one, and the redacted provider text.
+- Add the `pi` extractor for turns that keep the envelope type and carry the
+  refusal in `stopReason`/`errorMessage`, which no event-type match observes.
+  Such turns previously reached the caller as a clean run with empty content
+  while the process exited zero.
+- Default every other profile to the previously assumed shapes — dedicated
+  `error`, `turn.failed`, and `rate_limit_event` events plus failed `result`
+  events — so no existing profile changes behaviour.
+- Read usage from the assistant message and accept the bare
+  `input`/`output`/`cacheRead`/`cacheWrite` spellings, so a provider reporting
+  usage there is metered instead of silently recording nothing. The bare
+  spellings are matched last, leaving a provider that reports explicit
+  `*_tokens` keys with its existing reading.
+
+## 0.2.0 - 2026-08-15
+
+- Add first-class OpenCode `1.18.16+` support alongside the built-in Claude
+  Code, Codex CLI, Pi, and Grok CLI profiles. OpenCode uses the shared request
+  and facade, then adds provider-specific preparation, route probing, and
+  strict result normalization.
+- Route every OpenCode run to an exact `provider/model` and validate model
+  variants, preserving the route the application requested and the route the
+  captured result reports.
+- Prepare owner-private OpenCode config, data, cache, and state overlays for
+  each invocation, with scoped `read-only` and `workspace-write` policies,
+  deliberate credential forwarding, and idempotent cleanup.
+- Check run/export capabilities, selected authentication source, cached model
+  inventory, and the exact requested route locally before an application
+  starts work.
+- Correlate run and sanitized-export evidence into typed outcomes for
+  completion, authentication, configuration, CLI failure, malformed output,
+  cancellation, and timeout.
+- Report input, output, cache-read, cache-write, reasoning, and cost evidence
+  while preserving the difference between unavailable data and numeric zero.
+- Return prepared commands and normalized evidence through lifecycle-safe
+  values that fit an application's existing streaming, timeout, cancellation,
+  retry, and process-supervision stack.
+
 ## 0.1.1 - 2026-08-11
 
 - Expose each profile's immutable credential-environment key inventory so

data/README.md

@@ -1,22 +1,43 @@
 # Agent CLI Runtime
 
-`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.
+Agent CLI Runtime gives Ruby applications one stable integration layer for
+Claude Code, Codex CLI, Pi, Grok CLI, and OpenCode. It builds provider-specific
+commands from a shared request model, checks local versions and named
+capabilities, and normalizes usage and results afterward. Centralized profiles,
+environment rules, and parsers make agent providers easier to add, switch, and
+upgrade.
+
+Version 0.2.0 adds first-class OpenCode support with exact `provider/model`
+routing, isolated per-invocation configuration, scoped permission policies,
+offline readiness checks, and typed outcome normalization. See the
+[changelog](CHANGELOG.md) for the complete release notes.
+
+## Why use it?
+
+Agent CLIs disagree on flags, prompt transport, configuration locations,
+permission controls, usage events, and result formats. Agent CLI Runtime keeps
+those differences in versioned profiles so application code can use one
+request and result vocabulary.
+
+- Add or switch agent CLIs without spreading provider conditionals throughout
+  the application.
+- Validate installed versions, capabilities, and exact routes before starting
+  work.
+- Preserve typed usage and outcome evidence across provider-specific output
+  formats.
+- Add custom profiles through the same immutable compatibility contract.
 
 ## 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
 
@@ -39,6 +60,11 @@ Compilation does not execute the returned command. Unsupported requested
 controls raise `AgentCliRuntime::UnsupportedCapability` with typed evidence
 instead of silently widening the request.
 
+Prompt transport is profile-owned. `:stdin` writes the prompt to stdin and
+adds the CLI's conventional `-` argv marker; `:piped_stdin` writes the prompt
+to stdin without a marker for CLIs such as Pi that consume a non-TTY stream
+directly. Built-in Pi therefore keeps arbitrarily large prompts out of argv.
+
 `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.
@@ -56,6 +82,16 @@ 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)` returns a `PreparedInvocation` containing
+  an isolated OpenCode overlay, argv, and child environment.
+- `OpenCode::Permissions.compile(...)` returns the same deny-first permission
+  document independently for callers that retain native OpenCode state.
+- `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)` returns the non-model sanitized
+  session-export invocation.
+- `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 +144,138 @@ 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.
+
+Callers that deliberately retain native OpenCode config and login can use
+`OpenCode::Permissions.compile` directly and pass the JSON document through
+OpenCode's per-process permission input. The prepared-overlay API below
+remains the closed, isolated option.
+
+```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],
+  bash_patterns: ["git*", "bundle*", "bin/*"]
+)
+
+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. Shell is
+denied unless the caller supplies explicit OpenCode `bash_patterns`; those
+patterns are application permissions, not an OS sandbox. 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
+```
+
+Auto-discovery considers every matching executable in `PATH` and prefers an
+already-installed native executable over an earlier package-manager launcher,
+including script and multicall-binary shims, so the
+smoke cannot trigger package-manager installation or refresh behavior. If only
+a shim is discoverable, set `AGENT_CLI_RUNTIME_OPENCODE_OFFLINE_BIN` to the
+native OpenCode executable explicitly.
+
+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 +294,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 +340,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

@@ -5,12 +5,14 @@ Gem::Specification.new do |spec|
   spec.version = AgentCliRuntime::VERSION
   spec.authors = [ "Ivan Kuznetsov" ]
   spec.email = [ "ivan@ikuznetsov.com" ]
-  spec.summary = "Provider-neutral contracts for installed agent CLIs"
+  spec.summary =
+    "One Ruby API for Claude Code, Codex CLI, Pi, Grok CLI, and OpenCode"
   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.
+    Agent CLI Runtime gives Ruby applications one stable integration layer for
+    local coding-agent CLIs. It builds provider-specific commands from a shared
+    request model, checks local versions and named capabilities, and normalizes
+    usage and results afterward. Centralized profiles, environment rules, and
+    parsers make agent providers easier to add, switch, and upgrade.
   DESC
   spec.homepage = "https://github.com/ivankuznetsov/agent-cli-runtime"
   spec.license = "MIT"

data/lib/agent_cli_runtime/error_extractors.rb

@@ -0,0 +1,95 @@
+module AgentCliRuntime
+  # Provider-side failures that a CLI reports on its event stream while still
+  # exiting zero. Each profile owns the shape its own CLI emits. Extractors
+  # return either the raw provider text, an ExtractedFailure, or nil when the
+  # event carries no failure. Runtime.extract_provider_error normalizes and
+  # redacts the result.
+  module ErrorExtractors
+    module_function
+
+    # CLIs that name the failure with a dedicated event type. This is the same
+    # set Hive scanned for inline before provider shape moved behind the
+    # profile, so wiring a profile to DEFAULT preserves its behaviour.
+    DEFAULT = lambda do |event|
+      next nil unless event.is_a?(Hash)
+
+      case event["type"]
+      when "error", "turn.failed", "rate_limit_event"
+        ErrorExtractors.message_from(event)
+      when "result"
+        if event["is_error"] == true || event["subtype"].to_s.start_with?("error")
+          ErrorExtractors.message_from(event)
+        end
+      end
+    end
+
+    # Claude's subscription wall is a dedicated structured event with no
+    # human-readable message. The generic extractor therefore returned nil,
+    # leaving callers to flatten a rejected five-hour/seven-day window into a
+    # generic exit-code failure. Accept only the exact rejected account-window
+    # shapes observed from Claude Code and synthesize bounded provider text for
+    # the normal typed limit path. Other Claude errors retain DEFAULT behavior.
+    CLAUDE_ACCOUNT_LIMIT_TYPES = %w[five_hour seven_day].freeze
+    CLAUDE = lambda do |event|
+      if event.is_a?(Hash) && event["type"] == "rate_limit_event"
+        info = event["rate_limit_info"]
+        if info.is_a?(Hash) && info["status"] == "rejected"
+          limit_type = info["rateLimitType"].to_s
+          if CLAUDE_ACCOUNT_LIMIT_TYPES.include?(limit_type)
+            next ExtractedFailure.new(
+              kind: :provider_limit,
+              message: "Claude account quota reached (#{limit_type})"
+            )
+          end
+        end
+      end
+
+      DEFAULT.call(event)
+    end
+
+    # pi keeps the envelope type ("message_start"/"message_end") and moves the
+    # terminal state into stopReason. Provider refusals use
+    # stopReason=error/errorMessage. A model that consumes its entire output
+    # allowance uses stopReason=length and can exit zero without executing the
+    # final write tool. Matching on type alone sees neither failure.
+    PI = lambda do |event|
+      next nil unless event.is_a?(Hash)
+
+      message = event["message"].is_a?(Hash) ? event["message"] : event
+      case message["stopReason"].to_s
+      when "error"
+        ErrorExtractors.message_from(message) || ErrorExtractors.message_from(event)
+      when "length"
+        ExtractedFailure.new(
+          kind: :model_output_limit,
+          message: "model response reached its maximum output tokens"
+        )
+      end
+    end
+
+    # OpenCode keeps provider failures under error.data.message rather than
+    # the top-level/message and error.message shapes used by the default
+    # extractor. Read only the dedicated error event so ordinary model text
+    # cannot forge a provider-limit signal.
+    OPENCODE = lambda do |event|
+      next nil unless event.is_a?(Hash) && event["type"] == "error"
+
+      data = event.dig("error", "data")
+      message = data["message"] if data.is_a?(Hash)
+      message if message.is_a?(String) && !message.strip.empty?
+    end
+
+    def message_from(event)
+      return nil unless event.is_a?(Hash)
+
+      candidates = [
+        event["errorMessage"],
+        event["message"],
+        event.dig("error", "message"),
+        event["error"]
+      ]
+      text = candidates.find { |value| value.is_a?(String) && !value.strip.empty? }
+      text&.strip
+    end
+  end
+end

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