agent-cli-runtime 0.2.0 → 0.2.4

data/lib/agent_cli_runtime/opencode/permissions.rb

@@ -0,0 +1,144 @@
+require "json"
+
+module AgentCliRuntime
+  module OpenCode
+    # Compiles provider-neutral permission modes into OpenCode's
+    # per-run permission document. The document can be written into an
+    # isolated overlay or supplied through OPENCODE_PERMISSION while the CLI
+    # continues to use its native configuration and login.
+    module Permissions
+      module_function
+
+      def compile(permission_mode:, permission_policy: nil,
+                  working_directory:, additional_read_roots: [],
+                  additional_write_roots: [], edit_patterns: [],
+                  bash_patterns: [], plugins: [], runtime_write_roots: [])
+        mode = permission_mode
+        if mode.nil?
+          return nil unless permission_policy
+          unless permission_policy.is_a?(OpenCodePermissionPolicy)
+            raise ArgumentError,
+                  "permission_policy must be an OpenCodePermissionPolicy"
+          end
+
+          return deep_copy(permission_policy.rules)
+        end
+
+        unless %w[read-only workspace-write].include?(mode)
+          raise ConfigurationError, "unsupported OpenCode permission mode"
+        end
+
+        roots = {
+          working: File.expand_path(working_directory),
+          read: expanded_roots(additional_read_roots),
+          write: expanded_roots(additional_write_roots)
+        }
+        runtime_roots = expanded_roots(runtime_write_roots)
+        external = { "*" => "deny" }
+        [ *roots.fetch(:read), *roots.fetch(:write), *runtime_roots ].uniq.each do |root|
+          external[root] = "allow"
+          external["#{root}/**"] = "allow"
+        end
+        common = {
+          "*" => "deny",
+          "read" => {
+            "*" => "allow",
+            "*.env" => "deny",
+            "*.env.*" => "deny",
+            "*.env.example" => "allow"
+          },
+          "glob" => "allow",
+          "grep" => "allow",
+          "list" => "allow",
+          "lsp" => "allow",
+          "skill" => Array(plugins).empty? ? "deny" : "allow",
+          "external_directory" => external
+        }
+        if mode == "read-only"
+          return common.merge(
+            "edit" => "deny", "bash" => "deny", "task" => "deny",
+            "webfetch" => "deny", "websearch" => "deny",
+            "question" => "deny"
+          )
+        end
+
+        writable_roots = [
+          roots.fetch(:working), *roots.fetch(:write), *runtime_roots
+        ].uniq
+        edit = { "*" => "deny" }
+        allows = if Array(edit_patterns).empty?
+          writable_roots.flat_map do |root|
+            root_edit_patterns(root, working: roots.fetch(:working))
+          end
+        else
+          normalize_declared_edit_patterns(
+            edit_patterns, writable_roots, working: roots.fetch(:working)
+          )
+        end
+        allows.each { |pattern| edit[pattern] = "allow" }
+        (roots.fetch(:read) - roots.fetch(:write)).each do |root|
+          root_edit_patterns(root, working: roots.fetch(:working)).each do |pattern|
+            edit[pattern] = "deny"
+          end
+        end
+        bash = { "*" => "deny" }
+        Array(bash_patterns).each { |pattern| bash[pattern.to_s] = "allow" }
+        common.merge(
+          "edit" => edit,
+          "bash" => Array(bash_patterns).empty? ? "deny" : bash,
+          "task" => "deny",
+          "webfetch" => "deny", "websearch" => "deny",
+          "question" => "deny"
+        )
+      end
+
+      def expanded_roots(values)
+        Array(values).map { |value| File.expand_path(value) }.uniq.freeze
+      end
+      private_class_method :expanded_roots
+
+      def root_edit_patterns(root, working:)
+        if root == working
+          [ "**" ]
+        elsif root.start_with?(working + File::SEPARATOR)
+          relative = root.delete_prefix(working + File::SEPARATOR)
+          [ relative, "#{relative}/**" ]
+        else
+          [ root, "#{root}/**" ]
+        end
+      end
+      private_class_method :root_edit_patterns
+
+      def normalize_declared_edit_patterns(patterns, writable_roots, working:)
+        Array(patterns).map do |value|
+          pattern = value.to_s.sub(%r{\A//}, "/")
+          unless File.absolute_path?(pattern) && !pattern.include?("\0")
+            raise ConfigurationError,
+                  "OpenCode edit patterns must be absolute path patterns"
+          end
+          literal_prefix = pattern.split(/[*?]/, 2).first.sub(%r{/+\z}, "")
+          unless writable_roots.any? do |root|
+            literal_prefix == root ||
+              literal_prefix.start_with?(root + File::SEPARATOR)
+          end
+            raise ConfigurationError,
+                  "OpenCode edit pattern is outside the declared write roots"
+          end
+          if pattern == working
+            "**"
+          elsif pattern.start_with?(working + File::SEPARATOR)
+            pattern.delete_prefix(working + File::SEPARATOR)
+          else
+            pattern
+          end
+        end.uniq.freeze
+      end
+      private_class_method :normalize_declared_edit_patterns
+
+      def deep_copy(value)
+        JSON.parse(JSON.generate(value))
+      end
+      private_class_method :deep_copy
+    end
+  end
+end

data/lib/agent_cli_runtime/opencode/probe.rb

@@ -6,6 +6,7 @@ module AgentCliRuntime
       REQUIRED_RUN_FLAGS = %w[
         --model --variant --format --dir --pure --auto
       ].freeze
+      MODEL_INVENTORY_TIMEOUT_SECONDS = 30
       SAFE_ENVIRONMENT_KEYS = %w[
         HOME LANG LC_ALL LOGNAME PATH SHELL SSL_CERT_DIR SSL_CERT_FILE
         TMPDIR USER
@@ -19,11 +20,11 @@ module AgentCliRuntime
         call!(request, env:)
       rescue Error => e
         profile = Profiles.resolve(request.profile)
-        executable = profile.bin(env:)
+        executable = request.executable || profile.bin(env:)
         RouteProbeResult.new(
           provider: profile.name,
           ready: false,
-          installed: profile.binary_installed?(env:),
+          installed: profile.binary_installed?(env:, executable:),
           executable: executable,
           version: nil,
           minimum_version: profile.min_version,
@@ -54,20 +55,25 @@ module AgentCliRuntime
           raise ArgumentError,
                 "route-aware ProbeRequest currently requires profile :opencode"
         end
-        installed = profile.binary_installed?(env:)
+        installed = profile.binary_installed?(env:, executable: request.executable)
         unless installed
           raise BinaryUnavailable,
-                "opencode binary not runnable: #{profile.bin(env:)}"
+                "opencode binary not runnable: " \
+                "#{request.executable || profile.bin(env:)}"
         end
 
         child_env = child_environment(profile, request, env:)
-        version = profile.check_version!(env: child_env)
+        version = profile.check_version!(
+          env: child_env, executable: request.executable
+        )
         evidence = [
           evidence(profile, :installation),
           evidence(profile, :version, [ version ])
         ]
 
-        run_help = capture!(profile, child_env, "run", "--help")
+        run_help = capture!(
+          profile, child_env, "run", "--help", executable: request.executable
+        )
         missing = REQUIRED_RUN_FLAGS.reject { |flag| advertised?(run_help, flag) }
         unless missing.empty?
           raise UnsupportedCapability,
@@ -77,14 +83,18 @@ module AgentCliRuntime
           evidence(profile, capability_for(flag), [ flag ])
         end)
 
-        export_help = capture!(profile, child_env, "export", "--help")
+        export_help = capture!(
+          profile, child_env, "export", "--help", executable: request.executable
+        )
         unless advertised?(export_help, "--sanitize")
           raise UnsupportedCapability,
                 "OpenCode export is missing required --sanitize capability"
         end
         evidence << evidence(profile, :sanitized_export, [ "--sanitize" ])
 
-        auth_output = capture!(profile, child_env, "auth", "list")
+        auth_output = capture!(
+          profile, child_env, "auth", "list", executable: request.executable
+        )
         configured_key = request.credential_environment_keys.find do |key|
           !env[key].to_s.empty?
         end
@@ -106,19 +116,30 @@ module AgentCliRuntime
         )
         evidence << evidence(profile, :auth_configuration)
 
-        models_output = capture!(
-          profile, child_env, "models", request.route.provider, "--verbose"
-        )
-        variants = variants_for(models_output, request.route.to_s)
-        if variants.nil?
+        configured_variants = request.configured_variants
+        inventory_variants = if configured_variants.nil?
+          models_output = capture!(
+            profile, child_env, "models", request.route.provider, "--verbose",
+            executable: request.executable,
+            timeout_sec: MODEL_INVENTORY_TIMEOUT_SECONDS
+          )
+          variants_for(models_output, request.route.to_s)
+        end
+        if configured_variants.nil? && inventory_variants.nil?
           raise RouteUnavailable,
                 "requested OpenCode route is unavailable in the local model inventory"
         end
+        variants = [ *inventory_variants, *configured_variants ].uniq.sort.freeze
         if request.variant && !variants.include?(request.variant)
           raise RouteUnavailable,
                 "requested OpenCode variant is unavailable for the exact route"
         end
         evidence << evidence(profile, :model_route, [ request.route.to_s ])
+        if inventory_variants.nil?
+          evidence << evidence(
+            profile, :configured_model_route, [ request.route.to_s ]
+          )
+        end
         evidence << evidence(profile, :model_variant, [ request.variant ]) if
           request.variant
 
@@ -126,7 +147,7 @@ module AgentCliRuntime
           provider: profile.name,
           ready: true,
           installed: true,
-          executable: profile.bin(env: child_env),
+          executable: request.executable || profile.bin(env: child_env),
           version: version,
           minimum_version: profile.min_version,
           auth_configuration: auth,
@@ -165,8 +186,11 @@ module AgentCliRuntime
       end
       private_class_method :child_environment
 
-      def capture!(profile, environment, *arguments)
-        out, err, status = profile.capture_local(*arguments, env: environment)
+      def capture!(profile, environment, *arguments, executable: nil,
+                   timeout_sec: nil)
+        options = { env: environment, executable: executable }
+        options[:timeout_sec] = timeout_sec if timeout_sec
+        out, err, status = profile.capture_local(*arguments, **options)
         unless status.success?
           diagnostic = normalized_output("#{err}\n#{out}")
           raise ConfigurationError,

data/lib/agent_cli_runtime/opencode/result_parser.rb

@@ -4,7 +4,9 @@ module AgentCliRuntime
   module OpenCode
     module ResultParser
       MAX_RUN_BYTES = 4 * 1024 * 1024
-      MAX_EXPORT_BYTES = 4 * 1024 * 1024
+      # Sanitized exports contain the complete session and every tool result,
+      # so their bounded limit must accommodate long implementation sessions.
+      MAX_EXPORT_BYTES = 64 * 1024 * 1024
       MAX_FINAL_MESSAGE_BYTES = 1024 * 1024
       MAX_EVENTS = 10_000
       MAX_UNKNOWN_EVENTS = 16
@@ -22,8 +24,11 @@ module AgentCliRuntime
       AUTH_PATTERN = /auth|credential|api[ _-]?key|unauthorized|forbidden/i
       CONFIGURATION_PATTERN =
         /\b(?:Config(?:uration)?Error|UnknownProvider|UnknownModel|ModelNotFound|RouteUnavailable|VariantUnavailable)\b|\b(?:invalid|unknown|unsupported) (?:configuration|provider|model|route|variant)\b|\b(?:provider|model|route|variant)(?: [^\n]+)? (?:not found|unavailable)\b/i
+      UPSTREAM_TIMEOUT_PATTERN =
+        /\b(?:upstream\s+)?(?:idle\s+)?timeout\b|\btimed out\b|error_type['"\s:=>]+timeout\b|\bcode['"\s:=>]+504\b/i
       private_constant :KNOWN_EVENT_TYPES, :EVENT_PART_TYPES,
-                       :AUTH_PATTERN, :CONFIGURATION_PATTERN
+                       :AUTH_PATTERN, :CONFIGURATION_PATTERN,
+                       :UPSTREAM_TIMEOUT_PATTERN
 
       module_function
 
@@ -88,8 +93,6 @@ module AgentCliRuntime
         message = texts.filter_map do |message_id, text|
           text if message_id == terminal.fetch(:message_id)
         end.join
-        malformed!("OpenCode terminal assistant message is empty") if message.empty?
-
         final_message_truncated = message.bytesize > MAX_FINAL_MESSAGE_BYTES
         ParsedRun.new(
           session_id: session_id,
@@ -166,18 +169,21 @@ module AgentCliRuntime
         messages = export["messages"]
         malformed!("OpenCode sanitized export messages must be an array") unless
           messages.is_a?(Array)
-        matches = messages.filter_map do |message|
+        assistant = nil
+        messages.each do |message|
           next unless message.is_a?(Hash) && message["info"].is_a?(Hash)
 
           record = message.fetch("info")
           next unless record["id"] == message_id
 
-          record
+          if assistant
+            malformed!("OpenCode sanitized export must contain one terminal assistant record")
+          end
+          assistant = record
         end
-        unless matches.one?
+        unless assistant
           malformed!("OpenCode sanitized export must contain one terminal assistant record")
         end
-        assistant = matches.fetch(0)
         unless assistant["role"] == "assistant" &&
                assistant["sessionID"] == session_id
           malformed!("OpenCode sanitized export terminal record is not correlated")
@@ -208,7 +214,10 @@ module AgentCliRuntime
             cache_read: numeric(cache, "read", integer: true),
             cache_write: numeric(cache, "write", integer: true),
             reasoning: numeric(tokens, "reasoning", integer: true),
-            cost: numeric(assistant, "cost", integer: false)
+            input_includes_cache_read: cache.key?("read") ? true : nil,
+            input_includes_cache_write: cache.key?("write") ? true : nil,
+            output_includes_reasoning: tokens.key?("reasoning") ? false : nil,
+            provider_reported_cost: numeric(assistant, "cost", integer: false)
           )
         }.freeze
       rescue JSON::ParserError => e
@@ -231,7 +240,10 @@ module AgentCliRuntime
             cache_read: required_numeric(cache, "read", integer: true),
             cache_write: required_numeric(cache, "write", integer: true),
             reasoning: required_numeric(tokens, "reasoning", integer: true),
-            cost: required_numeric(part, "cost", integer: false)
+            input_includes_cache_read: true,
+            input_includes_cache_write: true,
+            output_includes_reasoning: false,
+            provider_reported_cost: required_numeric(part, "cost", integer: false)
           )
         }.freeze
       rescue ArgumentError => e
@@ -279,6 +291,8 @@ module AgentCliRuntime
             :authentication_failure
           elsif corpus.match?(CONFIGURATION_PATTERN)
             :configuration_failure
+          elsif corpus.match?(UPSTREAM_TIMEOUT_PATTERN)
+            :timed_out
           else
             :cli_failure
           end

data/lib/agent_cli_runtime/profile.rb

@@ -4,10 +4,10 @@ require "rubygems/version"
 
 module AgentCliRuntime
   class Profile
-    PROMPT_STYLES = %i[positional headless_flag_value stdin].freeze
+    PROMPT_STYLES = %i[positional headless_flag_value stdin piped_stdin].freeze
     WORKSPACE_WRITE_PERMISSION_MODE = "workspace-write".freeze
     READ_ONLY_PERMISSION_MODE = "read-only".freeze
-    CAPTURE_TIMEOUT_SECONDS = 10
+    CAPTURE_TIMEOUT_SECONDS = 120
     CAPTURE_POLL_SECONDS = 0.01
     CAPTURE_TERM_GRACE_SECONDS = 0.2
     CAPTURE_REAP_GRACE_SECONDS = 0.2
@@ -28,7 +28,8 @@ module AgentCliRuntime
                 :cli_capabilities, :declared_capability_support,
                 :credential_environment_keys, :configuration_environment_key,
                 :default_configuration_directory,
-                :permission_policy_required, :result_parser
+                :permission_policy_required, :result_parser,
+                :version_check_timeout_sec
 
     def initialize(name:, bin_default:, headless_flag:, version_flag:,
                    env_bin_override_keys: [], permission_skip_flag: nil,
@@ -37,11 +38,13 @@ module AgentCliRuntime
                    output_format_flags: [], min_version: nil,
                    prompt_style: :positional, model_argument_builder: nil,
                    effort_argument_builder: nil, launcher_identity: nil,
-                   usage_extractor: nil, auth_configuration_probe: nil,
+                   usage_extractor: nil, error_extractor: nil,
+                   auth_configuration_probe: nil,
                    cli_capabilities: {}, raw_cli_arguments_supported: false,
                    credential_environment_keys: [], configuration_environment_key: nil,
                    default_configuration_directory: nil,
-                   permission_policy_required: false, result_parser: nil)
+                   permission_policy_required: false, result_parser: nil,
+                   version_check_timeout_sec: CAPTURE_TIMEOUT_SECONDS)
       normalized_prompt_style = prompt_style.to_sym
       unless PROMPT_STYLES.include?(normalized_prompt_style)
         raise ArgumentError,
@@ -68,6 +71,7 @@ module AgentCliRuntime
       @launcher_identity =
         immutable_string(launcher_identity || "agent-cli-runtime/v1:#{@name}")
       @usage_extractor = usage_extractor || ->(_event) { nil }
+      @error_extractor = error_extractor || ErrorExtractors::DEFAULT
       @auth_configuration_probe = auth_configuration_probe
       @cli_capabilities = normalize_cli_capabilities(cli_capabilities)
       @raw_cli_arguments_supported = raw_cli_arguments_supported == true
@@ -82,6 +86,10 @@ module AgentCliRuntime
       )
       @permission_policy_required = permission_policy_required == true
       @result_parser = result_parser
+      @version_check_timeout_sec = Float(version_check_timeout_sec)
+      unless @version_check_timeout_sec.positive?
+        raise ArgumentError, "version_check_timeout_sec must be positive"
+      end
       @declared_capability_support = build_declared_capability_support
       freeze
     end
@@ -153,8 +161,8 @@ module AgentCliRuntime
       @raw_cli_arguments_supported
     end
 
-    def binary_installed?(env: ENV)
-      executable = bin(env:)
+    def binary_installed?(env: ENV, executable: nil)
+      executable ||= bin(env:)
       return File.file?(executable) && File.executable?(executable) if executable.include?(File::SEPARATOR)
 
       env.fetch("PATH", "").split(File::PATH_SEPARATOR).any? do |directory|
@@ -165,10 +173,10 @@ module AgentCliRuntime
       false
     end
 
-    def check_version!(env: ENV)
-      executable = bin(env:)
+    def check_version!(env: ENV, executable: nil)
+      executable ||= bin(env:)
       out, _err, status = bounded_capture3(
-        executable, @version_flag, timeout_sec: CAPTURE_TIMEOUT_SECONDS, env: env
+        executable, @version_flag, timeout_sec: @version_check_timeout_sec, env: env
       )
       unless status.success?
         raise BinaryUnavailable,
@@ -197,7 +205,7 @@ module AgentCliRuntime
             "#{@name} binary not runnable: #{executable} (#{e.class.name.split('::').last})"
     rescue Timeout::Error
       raise BinaryUnavailable,
-            "#{@name} version check timed out after #{CAPTURE_TIMEOUT_SECONDS}s: #{executable}"
+            "#{@name} version check timed out after #{@version_check_timeout_sec}s: #{executable}"
     end
 
     def auth_configuration(home: nil, env: ENV)
@@ -221,6 +229,12 @@ module AgentCliRuntime
       nil
     end
 
+    def extract_error_event(event)
+      @error_extractor.call(event)
+    rescue StandardError
+      nil
+    end
+
     def parse_run(stdout)
       unless @result_parser
         raise UnsupportedCapability,
@@ -278,9 +292,10 @@ module AgentCliRuntime
       flags.dup
     end
 
-    def capture_local(*arguments, env: ENV, timeout_sec: CAPTURE_TIMEOUT_SECONDS)
+    def capture_local(*arguments, env: ENV, timeout_sec: CAPTURE_TIMEOUT_SECONDS,
+                      executable: nil)
       bounded_capture3(
-        bin(env:), *arguments, timeout_sec: timeout_sec, env: env
+        executable || bin(env:), *arguments, timeout_sec: timeout_sec, env: env
       )
     end
 

data/lib/agent_cli_runtime/profiles.rb

@@ -139,6 +139,8 @@ module AgentCliRuntime
       bin_default: "claude",
       env_bin_override_keys: %w[AGENT_CLI_RUNTIME_CLAUDE_BIN HIVE_CLAUDE_BIN],
       headless_flag: "-p",
+      # Print mode reads stdin; keep large review prompts out of exec arguments.
+      prompt_style: :piped_stdin,
       permission_skip_flag: "--dangerously-skip-permissions",
       add_dir_flag: "--add-dir",
       tool_scope_flags: {
@@ -156,6 +158,7 @@ module AgentCliRuntime
       effort_argument_builder: ->(effort) { [ "--effort", effort ] },
       launcher_identity: "claude-code/v1",
       usage_extractor: UsageExtractors::CLAUDE,
+      error_extractor: ErrorExtractors::CLAUDE,
       credential_environment_keys: %w[
         ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN CLAUDE_API_KEY
       ],
@@ -220,12 +223,17 @@ module AgentCliRuntime
       bin_default: "pi",
       env_bin_override_keys: %w[AGENT_CLI_RUNTIME_PI_BIN HIVE_PI_BIN],
       headless_flag: "-p",
+      # Pi reads a non-TTY stdin stream into its initial message without an
+      # argv placeholder. Keeping the prompt out of argv also avoids Linux's
+      # per-argument size limit on real implementation plans.
+      prompt_style: :piped_stdin,
       output_format_flags: [ "--mode", "json", "--no-session" ],
       version_flag: "--version",
       min_version: "0.70.2",
       model_argument_builder: ->(model) { [ "--model", model ] },
       launcher_identity: "pi-coding-agent/v1",
       usage_extractor: UsageExtractors::PI,
+      error_extractor: ErrorExtractors::PI,
       credential_environment_keys: PI_CREDENTIAL_ENVIRONMENT_KEYS,
       configuration_environment_key: "PI_CODING_AGENT_DIR",
       default_configuration_directory: ".pi/agent",
@@ -247,9 +255,18 @@ module AgentCliRuntime
       name: :grok,
       bin_default: "grok",
       env_bin_override_keys: %w[AGENT_CLI_RUNTIME_GROK_BIN HIVE_GROK_BIN],
-      headless_flag: "-p",
-      prompt_style: :headless_flag_value,
+      # Grok's Unix CLI reads a prompt file; stdin already has a managed lifetime.
+      headless_flag: "--prompt-file=/dev/stdin",
+      prompt_style: :piped_stdin,
       permission_skip_flag: "--always-approve",
+      # Grok confines the filesystem natively, the same shape codex uses.
+      # `workspace` limits writes to the working directory, `read-only`
+      # forbids them entirely; both are built-in profiles (custom ones extend
+      # them from ~/.grok/sandbox.toml). `--always-approve` suppresses the
+      # interactive approval prompt, which a headless reviewer can never answer
+      # — the sandbox, not the prompt, is what actually bounds the agent.
+      workspace_write_flags: [ "--sandbox", "workspace", "--always-approve" ],
+      read_only_flags: [ "--sandbox", "read-only", "--always-approve" ],
       output_format_flags: [ "--output-format", "streaming-json" ],
       version_flag: "--version",
       min_version: "0.2.90",
@@ -282,6 +299,14 @@ module AgentCliRuntime
       headless_flag: "run",
       output_format_flags: [ "--format", "json" ],
       version_flag: "--version",
+      # `opencode run` reads a non-TTY stdin stream as the initial message.
+      # Keep implementation-sized prompts out of one argv element: Linux
+      # rejects a single argument around 128 KiB with E2BIG even when the
+      # complete argv remains far below ARG_MAX.
+      prompt_style: :piped_stdin,
+      # Bun-backed OpenCode startup can exceed the generic 10-second bound
+      # under sustained host I/O even though the executable is healthy.
+      version_check_timeout_sec: 30,
       min_version: "1.18.16",
       model_argument_builder: ->(model) { opencode_model_arguments(model) },
       effort_argument_builder:
@@ -291,6 +316,7 @@ module AgentCliRuntime
       configuration_environment_key: "OPENCODE_CONFIG_DIR",
       default_configuration_directory: ".config/opencode",
       permission_policy_required: true,
+      error_extractor: ErrorExtractors::OPENCODE,
       result_parser: OpenCode::ResultParser,
       cli_capabilities: {
         json_events: [ "run", "--format" ],