agent-cli-runtime 0.1.1 → 0.2.4

data/lib/agent_cli_runtime/opencode/result_parser.rb

@@ -0,0 +1,416 @@
+require "json"
+
+module AgentCliRuntime
+  module OpenCode
+    module ResultParser
+      MAX_RUN_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
+      TERMINAL_REASONS = %w[stop length content-filter].freeze
+      KNOWN_EVENT_TYPES = %w[
+        step_start step_finish text reasoning tool_use error
+      ].freeze
+      EVENT_PART_TYPES = {
+        "step_start" => "step-start",
+        "step_finish" => "step-finish",
+        "text" => "text",
+        "reasoning" => "reasoning",
+        "tool_use" => "tool"
+      }.freeze
+      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,
+                       :UPSTREAM_TIMEOUT_PATTERN
+
+      module_function
+
+      def parse_run(stdout)
+        bounded_input!(stdout, MAX_RUN_BYTES, "OpenCode run output")
+        session_id = nil
+        terminal = nil
+        texts = []
+        unknown = []
+        error_seen = false
+        event_count = 0
+
+        stdout.each_line.with_index(1) do |line, line_number|
+          next if line.strip.empty?
+
+          event_count += 1
+          malformed!("OpenCode run output contains too many events") if
+            event_count > MAX_EVENTS
+          event = parse_json_line(line, line_number)
+          type = required_string(event, "type", "event type")
+          unless KNOWN_EVENT_TYPES.include?(type)
+            additive_session = validate_additive_session!(event, session_id)
+            session_id ||= additive_session
+            if unknown.length < MAX_UNKNOWN_EVENTS
+              unknown << Redactor.diagnostic(
+                "unknown OpenCode event #{type}", bytes: 128
+              )
+            end
+            next
+          end
+
+          event_session = required_string(event, "sessionID", "event sessionID")
+          session_id ||= event_session
+          malformed!("OpenCode run sessionID changed within one capture") unless
+            session_id == event_session
+
+          if type == "error"
+            validate_error!(event)
+            error_seen = true
+            next
+          end
+
+          part = required_hash(event, "part", "event part")
+          validate_part!(part, type, session_id)
+          message_id = required_string(part, "messageID", "part messageID")
+          case type
+          when "text"
+            text = part["text"]
+            malformed!("OpenCode text part must contain text") unless
+              text.is_a?(String)
+            texts << [ message_id, text ]
+          when "step_finish"
+            terminal = terminal_part(part, message_id)
+          end
+        end
+
+        malformed!("OpenCode run emitted an error on a zero exit") if error_seen
+        malformed!("OpenCode run has no recognized terminal step") unless terminal
+        unless TERMINAL_REASONS.include?(terminal.fetch(:reason))
+          malformed!("OpenCode terminal step has an unrecognized finish reason")
+        end
+        message = texts.filter_map do |message_id, text|
+          text if message_id == terminal.fetch(:message_id)
+        end.join
+        final_message_truncated = message.bytesize > MAX_FINAL_MESSAGE_BYTES
+        ParsedRun.new(
+          session_id: session_id,
+          terminal_message_id: terminal.fetch(:message_id),
+          terminal_reason: terminal.fetch(:reason),
+          final_message: bounded_string(message, MAX_FINAL_MESSAGE_BYTES),
+          final_message_truncated: final_message_truncated,
+          preliminary_usage: terminal.fetch(:usage),
+          unknown_events: unknown.compact
+        )
+      rescue MalformedOutput
+        raise
+      rescue StandardError => e
+        raise MalformedOutput, Redactor.diagnostic(e)
+      end
+
+      def normalize(captured, requested_route:, profile:)
+        unless captured.is_a?(CapturedResult)
+          raise ArgumentError, "captured must be an AgentCliRuntime::CapturedResult"
+        end
+        route = requested_route.is_a?(Route) ?
+          requested_route : Route.parse(requested_route)
+        termination = captured.termination
+        return failure_outcome(
+          profile, route, termination, :timed_out, "OpenCode run timed out"
+        ) if termination.timed_out
+        return failure_outcome(
+          profile, route, termination, :cancelled, "OpenCode run was cancelled"
+        ) if termination.cancelled
+        unless termination.success?
+          kind, diagnostic = classify_failure(captured)
+          return failure_outcome(
+            profile, route, termination, kind, diagnostic
+          )
+        end
+
+        parsed = parse_run(captured.stdout)
+        inspection = parse_inspection(
+          captured.inspection_output,
+          session_id: parsed.session_id,
+          message_id: parsed.terminal_message_id
+        )
+        actual = inspection.fetch(:route)
+        NormalizedOutcome.new(
+          provider: profile.name,
+          launcher_identity: profile.launcher_identity,
+          kind: :completed,
+          termination: termination,
+          final_message: parsed.final_message,
+          final_message_truncated: parsed.final_message_truncated,
+          identity: RouteIdentity.new(requested: route, actual: actual),
+          usage: inspection.fetch(:usage),
+          diagnostic: nil,
+          unknown_events: parsed.unknown_events,
+          session_id: parsed.session_id,
+          message_id: parsed.terminal_message_id
+        )
+      rescue MalformedOutput => e
+        malformed_outcome(profile, requested_route, captured, e)
+      end
+
+      def parse_inspection(output, session_id:, message_id:)
+        if output.nil?
+          malformed!("OpenCode sanitized export evidence is required")
+        end
+        bounded_input!(output, MAX_EXPORT_BYTES, "OpenCode sanitized export")
+        export = JSON.parse(output)
+        malformed!("OpenCode sanitized export must be an object") unless
+          export.is_a?(Hash)
+        info = required_hash(export, "info", "export info")
+        unless required_string(info, "id", "export session id") == session_id
+          malformed!("OpenCode sanitized export session does not match the run")
+        end
+        messages = export["messages"]
+        malformed!("OpenCode sanitized export messages must be an array") unless
+          messages.is_a?(Array)
+        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
+
+          if assistant
+            malformed!("OpenCode sanitized export must contain one terminal assistant record")
+          end
+          assistant = record
+        end
+        unless assistant
+          malformed!("OpenCode sanitized export must contain one terminal assistant record")
+        end
+        unless assistant["role"] == "assistant" &&
+               assistant["sessionID"] == session_id
+          malformed!("OpenCode sanitized export terminal record is not correlated")
+        end
+        unless TERMINAL_REASONS.include?(assistant["finish"])
+          malformed!("OpenCode sanitized export terminal record is incomplete")
+        end
+        provider = required_string(
+          assistant, "providerID", "assistant providerID"
+        )
+        model = required_string(assistant, "modelID", "assistant modelID")
+        tokens = assistant["tokens"]
+        unless tokens.nil? || tokens.is_a?(Hash)
+          malformed!("OpenCode assistant tokens must be an object")
+        end
+        tokens ||= {}
+        cache = tokens["cache"]
+        unless cache.nil? || cache.is_a?(Hash)
+          malformed!("OpenCode assistant cache tokens must be an object")
+        end
+        cache ||= {}
+
+        {
+          route: Route.new(provider:, model:),
+          usage: NormalizedUsage.new(
+            input: numeric(tokens, "input", integer: true),
+            output: numeric(tokens, "output", integer: true),
+            cache_read: numeric(cache, "read", integer: true),
+            cache_write: numeric(cache, "write", integer: true),
+            reasoning: numeric(tokens, "reasoning", integer: true),
+            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
+        raise MalformedOutput,
+              Redactor.diagnostic("OpenCode sanitized export is malformed: #{e.message}")
+      rescue ArgumentError => e
+        raise MalformedOutput, Redactor.diagnostic(e)
+      end
+
+      def terminal_part(part, message_id)
+        reason = required_string(part, "reason", "terminal reason")
+        tokens = required_hash(part, "tokens", "terminal tokens")
+        cache = required_hash(tokens, "cache", "terminal cache tokens")
+        {
+          message_id: message_id,
+          reason: reason,
+          usage: NormalizedUsage.new(
+            input: required_numeric(tokens, "input", integer: true),
+            output: required_numeric(tokens, "output", integer: true),
+            cache_read: required_numeric(cache, "read", integer: true),
+            cache_write: required_numeric(cache, "write", integer: true),
+            reasoning: required_numeric(tokens, "reasoning", integer: true),
+            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
+        malformed!(e.message)
+      end
+      private_class_method :terminal_part
+
+      def validate_part!(part, event_type, session_id)
+        expected = EVENT_PART_TYPES.fetch(event_type)
+        unless part["type"] == expected && part["sessionID"] == session_id
+          malformed!("OpenCode #{event_type} part is not correlated")
+        end
+        required_string(part, "id", "part id")
+      end
+      private_class_method :validate_part!
+
+      def validate_error!(event)
+        error = required_hash(event, "error", "error event payload")
+        required_string(error, "name", "error name")
+        data = required_hash(error, "data", "error data")
+        required_string(data, "message", "error message")
+      end
+      private_class_method :validate_error!
+
+      def validate_additive_session!(event, session_id)
+        value = event["sessionID"]
+        return nil if value.nil?
+        unless value.is_a?(String) && !value.empty? && !value.include?("\0")
+          malformed!("OpenCode additive event sessionID must be a non-empty string")
+        end
+        return value if session_id.nil? || value == session_id
+
+        malformed!("OpenCode additive event session does not match the run")
+      end
+      private_class_method :validate_additive_session!
+
+      def classify_failure(captured)
+        details = error_details(captured.stdout)
+        diagnostic = Redactor.diagnostic(
+          [ *details, captured.stderr ].reject(&:empty?).join("\n")
+        ) || "OpenCode CLI exited without diagnostic evidence"
+        corpus = [ *details, captured.stderr ].join(" ")
+        kind =
+          if corpus.match?(AUTH_PATTERN)
+            :authentication_failure
+          elsif corpus.match?(CONFIGURATION_PATTERN)
+            :configuration_failure
+          elsif corpus.match?(UPSTREAM_TIMEOUT_PATTERN)
+            :timed_out
+          else
+            :cli_failure
+          end
+        [ kind, diagnostic ]
+      end
+      private_class_method :classify_failure
+
+      def error_details(stdout)
+        return [] if stdout.bytesize > MAX_RUN_BYTES
+
+        stdout.each_line.filter_map do |line|
+          event = JSON.parse(line)
+          next unless event.is_a?(Hash) && event["type"] == "error"
+
+          error = event["error"]
+          next unless error.is_a?(Hash)
+
+          name = error["name"].to_s
+          data = error["data"]
+          message = data.is_a?(Hash) ? data["message"].to_s : ""
+          [ name, message ].reject(&:empty?).join(": ")
+        rescue JSON::ParserError
+          nil
+        end
+      end
+      private_class_method :error_details
+
+      def failure_outcome(profile, route, termination, kind, diagnostic)
+        NormalizedOutcome.new(
+          provider: profile.name,
+          launcher_identity: profile.launcher_identity,
+          kind: kind,
+          termination: termination,
+          identity: RouteIdentity.new(requested: route),
+          diagnostic: Redactor.diagnostic(diagnostic)
+        )
+      end
+      private_class_method :failure_outcome
+
+      def malformed_outcome(profile, requested_route, captured, error)
+        route = requested_route.is_a?(Route) ?
+          requested_route : Route.parse(requested_route)
+        NormalizedOutcome.new(
+          provider: profile.name,
+          launcher_identity: profile.launcher_identity,
+          kind: :malformed_output,
+          termination: captured.termination,
+          identity: RouteIdentity.new(requested: route),
+          diagnostic: Redactor.diagnostic(error)
+        )
+      end
+      private_class_method :malformed_outcome
+
+      def parse_json_line(line, line_number)
+        value = JSON.parse(line)
+        malformed!("OpenCode event on line #{line_number} must be an object") unless
+          value.is_a?(Hash)
+        value
+      rescue JSON::ParserError
+        malformed!("OpenCode run output has malformed JSON on line #{line_number}")
+      end
+      private_class_method :parse_json_line
+
+      def required_hash(hash, key, label)
+        value = hash[key]
+        malformed!("OpenCode #{label} must be an object") unless value.is_a?(Hash)
+        value
+      end
+      private_class_method :required_hash
+
+      def required_string(hash, key, label)
+        value = hash[key]
+        unless value.is_a?(String) && !value.empty? && !value.include?("\0")
+          malformed!("OpenCode #{label} must be a non-empty string")
+        end
+        value
+      end
+      private_class_method :required_string
+
+      def required_numeric(hash, key, integer:)
+        malformed!("OpenCode #{key} is required") unless hash.key?(key)
+        numeric(hash, key, integer:)
+      end
+      private_class_method :required_numeric
+
+      def numeric(hash, key, integer:)
+        return nil unless hash.key?(key)
+
+        value = hash[key]
+        valid = integer ? value.is_a?(Integer) : value.is_a?(Numeric)
+        valid &&= value.finite? if value.respond_to?(:finite?)
+        unless valid && value >= 0
+          malformed!("OpenCode #{key} must be a non-negative number")
+        end
+        value
+      end
+      private_class_method :numeric
+
+      def bounded_input!(value, bytes, label)
+        unless value.is_a?(String) && value.bytesize <= bytes
+          malformed!("#{label} exceeds the bounded input size")
+        end
+      end
+      private_class_method :bounded_input!
+
+      def bounded_string(value, bytes)
+        return value if value.bytesize <= bytes
+
+        value.byteslice(0, bytes).to_s
+             .force_encoding(Encoding::UTF_8)
+             .scrub("?")
+      end
+      private_class_method :bounded_string
+
+      def malformed!(message)
+        raise MalformedOutput, Redactor.diagnostic(message)
+      end
+      private_class_method :malformed!
+    end
+  end
+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
@@ -27,7 +27,9 @@ module AgentCliRuntime
                 :effort_argument_builder, :launcher_identity,
                 :cli_capabilities, :declared_capability_support,
                 :credential_environment_keys, :configuration_environment_key,
-                :default_configuration_directory
+                :default_configuration_directory,
+                :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,
@@ -36,10 +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)
+                   default_configuration_directory: 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,
@@ -66,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
@@ -78,6 +84,12 @@ module AgentCliRuntime
       @default_configuration_directory = optional_relative_directory(
         default_configuration_directory
       )
+      @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
@@ -102,6 +114,10 @@ module AgentCliRuntime
         raise ArgumentError,
               "agent profile #{@name.inspect} cannot enforce read-only sandboxing"
       end
+      if permission_mode.nil? && @permission_policy_required
+        raise ConfigurationError,
+              "agent profile #{@name.inspect} requires an explicit OpenCode permission policy"
+      end
       return [] unless @permission_skip_flag
       return [ @permission_skip_flag ] unless @name == :claude && permission_mode
       return [ @permission_skip_flag ] if permission_mode == "bypassPermissions"
@@ -145,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|
@@ -157,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,
@@ -189,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)
@@ -213,6 +229,32 @@ 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,
+              "agent profile #{@name.inspect} has no strict result parser"
+      end
+
+      @result_parser.parse_run(stdout)
+    end
+
+    def normalize_captured_result(captured, requested_route:)
+      unless @result_parser
+        raise UnsupportedCapability,
+              "agent profile #{@name.inspect} has no strict result parser"
+      end
+
+      @result_parser.normalize(
+        captured, requested_route: requested_route, profile: self
+      )
+    end
+
     def configuration_directory(home: nil, env: ENV)
       if @configuration_environment_key
         configured = env[@configuration_environment_key].to_s
@@ -250,6 +292,13 @@ module AgentCliRuntime
       flags.dup
     end
 
+    def capture_local(*arguments, env: ENV, timeout_sec: CAPTURE_TIMEOUT_SECONDS,
+                      executable: nil)
+      bounded_capture3(
+        executable || bin(env:), *arguments, timeout_sec: timeout_sec, env: env
+      )
+    end
+
     private
 
     def immutable_string(value)