ace-llm 0.41.1 → 0.42.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: be27933d1e68809cb7b94334d46cd97f41ad6d90426da9a707f7e3b80a6e3a3c
-  data.tar.gz: 0ce33a24a57a2d38ba1400cebaf3d9e44b51f1a25336ae925669c75c7ca62ac4
+  metadata.gz: 5b93f7041470f94d60776c4d9659cd403909a02777f3e8f6453e040cb62d5ae7
+  data.tar.gz: 812993967a5d36cedfccc9a1789303ca8abd9882fb5b53d7d2eda7413e82488f
 SHA512:
-  metadata.gz: 7ef60bd90eaad66f91b2633e7453b1bac297bc5804d74619b6939b4bfea318328a5ffa28a641fa70f3a0398b1e11e7ccce8e9669cf354b7aa713e80e4c51e9ad
-  data.tar.gz: 795ecb19d4864a89128f54741d328f7e374c0c239530200593bde3b9252222047f03723d43cfab7f4809ebad0c05b135b55c97c7e1eb72ca77fa2b0116b16235
+  metadata.gz: 497b2a465fd61863b06b4b4a4da6f5c1919bdf3a6228e1964994a0204fa0bcdf7c78870f1717f43ba485c0cfd4a1d4ca5d72430c4add742853c95b69c176dfa4
+  data.tar.gz: a1fc3830077342a69ad444ff03f80e88f4ac899d4a2dc9f71b485f33262c772790fd46231ecba3fd82e2bc47a4445f779fd429df25b7247ce1f3e8adc88952fd

data/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.42.0] - 2026-09-29
+
+### Added
+- `Ace::LLM::Models::ExecutionEvidence`: structured, immutable record of how a CLI provider execution actually ended (outcome kind, invocation correlation ID, configured deadline, monotonic elapsed time, exit status/signal, bounded output excerpts). `Ace::LLM::ProviderError` instances can now carry it via `execution_evidence`.
+
+### Changed
+- `ErrorClassifier` prefers structured execution evidence over error-message prose and returns the new `EXECUTION_INCOMPLETE` classification when a provider session began and then ended without a confirmed completion (deadline expiry, transport drop, nonzero exit, or clean exit without a final response). A nonzero exit whose stderr merely mentions "timeout" is no longer classified as a timeout; a successful response containing the word is unaffected.
+- `FallbackOrchestrator` aborts the whole chain (no retry, no fallback) on execution-incomplete failures — the provider process already ran, so replaying via another provider would repeat its side effects. The terminal error carries the evidence summary, the provider's own bounded diagnostic line, and the list of tried providers; all-providers-exhausted messages include the last execution evidence.
+
 ## [0.41.1] - 2026-09-29
 
 ### Changed

data/lib/ace/llm/atoms/error_classifier.rb

@@ -11,6 +11,11 @@ module Ace
         FALLBACK_IMMEDIATELY = :fallback_immediately
         SKIP_TO_NEXT = :skip_to_next
         TERMINAL = :terminal
+        # The provider process started but its session ended without a confirmed
+        # completion (deadline expiry, transport drop, nonzero exit, or a clean
+        # exit without a final response). Such sessions may have performed side
+        # effects — retries and fallback would replay them.
+        EXECUTION_INCOMPLETE = :execution_incomplete
 
         # Map HTTP status codes to classification
         STATUS_CLASSIFICATIONS = {
@@ -43,8 +48,13 @@ module Ace
 
         # Classify an error for retry/fallback decisions
         # @param error [Exception] The error to classify
-        # @return [Symbol] Classification type (RETRYABLE_WITH_BACKOFF, FALLBACK_IMMEDIATELY, SKIP_TO_NEXT, TERMINAL)
+        # @return [Symbol] Classification type (RETRYABLE_WITH_BACKOFF, FALLBACK_IMMEDIATELY, SKIP_TO_NEXT, TERMINAL, EXECUTION_INCOMPLETE)
         def self.classify(error)
+          # Structured capture evidence attached at the subprocess boundary
+          # outranks message prose: a nonzero exit whose stderr mentions
+          # "timeout" is a nonzero exit, not a deadline expiry.
+          return EXECUTION_INCOMPLETE if execution_incomplete?(error)
+
           case error
           when Ace::LLM::AuthenticationError
             SKIP_TO_NEXT
@@ -64,6 +74,31 @@ module Ace
           end
         end
 
+        # True when the error carries structured evidence that the provider
+        # execution began and ended without a confirmed completion.
+        # @param error [Exception]
+        # @return [Boolean]
+        def self.execution_incomplete?(error)
+          evidence = execution_evidence_for(error)
+          evidence&.uncertain_execution? ? true : false
+        end
+
+        # Extract structured execution evidence from an error, accepting either
+        # an ExecutionEvidence instance or its serialized hash form.
+        # @param error [Exception]
+        # @return [Ace::LLM::Models::ExecutionEvidence, nil]
+        def self.execution_evidence_for(error)
+          return nil unless error.respond_to?(:execution_evidence)
+
+          evidence = error.execution_evidence
+          case evidence
+          when Ace::LLM::Models::ExecutionEvidence
+            evidence
+          when Hash
+            Ace::LLM::Models::ExecutionEvidence.from_h(evidence)
+          end
+        end
+
         # Determine if an error is retryable
         # @param error [Exception] The error to check
         # @return [Boolean] True if error should be retried

data/lib/ace/llm/models/execution_evidence.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Ace
+  module LLM
+    module Models
+      # Structured evidence about how a CLI provider execution actually ended.
+      #
+      # Built at the subprocess boundary (ace-llm-providers-cli SafeCapture) and
+      # attached to Ace::LLM::ProviderError instances so classification and
+      # fallback decisions can key on observed process facts instead of error
+      # message prose. Carries bounded output excerpts only — never the full
+      # streams, prompt content, or environment.
+      #
+      # This is a model - pure immutable data.
+      class ExecutionEvidence
+        OUTCOMES = %i[
+          deadline_exceeded
+          transport_failure
+          nonzero_exit
+          no_response
+        ].freeze
+
+        EXCERPT_LIMIT = 2000
+
+        # Credential shapes that must not survive into diagnostics, reports, or
+        # error messages. Matches are truncated to a short prefix so the
+        # credential TYPE stays readable while the value is destroyed.
+        SECRET_PATTERNS = [
+          /(?:bearer|authorization|basic)\s*[:=]?\s*[\w.\-+=\/]{8,}/i,
+          /(?:api[_-]?key|access[_-]?token|auth[_-]?token|refresh[_-]?token|client[_-]?secret|secret|password|passwd|pwd)\s*["']?\s*[:=]\s*["']?[\w.\-+=\/]{8,}/i,
+          /sk-(?:proj-)?[A-Za-z0-9_\-]{16,}/,
+          /gh[pousr]_[A-Za-z0-9_]{16,}/,
+          /AKIA[0-9A-Z]{16}/,
+          /xox[baprs]-[A-Za-z0-9\-]{10,}/,
+          /eyJ[A-Za-z0-9_\-]{20,}\.eyJ[A-Za-z0-9_\-]{20,}\.[A-Za-z0-9_\-]{10,}/
+        ].freeze
+
+        # Destroy credential values in captured diagnostics while keeping the
+        # surrounding text readable.
+        # @param text [String, nil]
+        # @return [String, nil]
+        def self.redact(text)
+          return text if text.nil?
+
+          redacted = text.to_s.dup
+          SECRET_PATTERNS.each do |pattern|
+            redacted = redacted.gsub(pattern) { |match| "#{match[0, 6]}…[redacted]" }
+          end
+          redacted
+        end
+
+        attr_reader :outcome, :invocation_id, :provider_name, :deadline_seconds,
+          :elapsed_seconds, :exit_status, :signal, :execution_began,
+          :stdout_excerpt, :stderr_excerpt
+
+        # @param outcome [Symbol] one of OUTCOMES
+        # @param invocation_id [String, nil] opaque correlation ID generated before spawn
+        # @param provider_name [String, nil] human-facing provider label (e.g. "Codex")
+        # @param deadline_seconds [Numeric, nil] configured deadline for the invocation
+        # @param elapsed_seconds [Numeric, nil] monotonic elapsed time of the invocation
+        # @param exit_status [Integer, nil] process exit code when the process exited
+        # @param signal [String, nil] signal name when the process was terminated by one
+        # @param execution_began [Boolean] true when the provider process was actually spawned
+        # @param stdout_excerpt [String, nil] bounded excerpt of captured stdout
+        # @param stderr_excerpt [String, nil] bounded excerpt of captured stderr
+        def initialize(outcome:, invocation_id: nil, provider_name: nil, deadline_seconds: nil,
+          elapsed_seconds: nil, exit_status: nil, signal: nil, execution_began: true,
+          stdout_excerpt: nil, stderr_excerpt: nil)
+          raise ArgumentError, "unknown outcome #{outcome.inspect}" unless OUTCOMES.include?(outcome)
+
+          @outcome = outcome
+          @invocation_id = invocation_id
+          @provider_name = provider_name
+          @deadline_seconds = deadline_seconds
+          @elapsed_seconds = elapsed_seconds
+          @exit_status = exit_status
+          @signal = signal
+          @execution_began = execution_began
+          @stdout_excerpt = bounded_excerpt(stdout_excerpt)
+          @stderr_excerpt = bounded_excerpt(stderr_excerpt)
+          freeze
+        end
+
+        # Build evidence from a plain hash (e.g. deserialized metadata)
+        # @param hash [Hash]
+        # @return [ExecutionEvidence]
+        def self.from_h(hash)
+          return nil unless hash.is_a?(Hash)
+
+          symbolized = hash.each_with_object({}) { |(key, value), acc| acc[key.to_sym] = value }
+          outcome = symbolized[:outcome].to_s.to_sym
+          return nil unless OUTCOMES.include?(outcome)
+
+          new(
+            outcome: outcome,
+            invocation_id: symbolized[:invocation_id],
+            provider_name: symbolized[:provider_name],
+            deadline_seconds: symbolized[:deadline_seconds],
+            elapsed_seconds: symbolized[:elapsed_seconds],
+            exit_status: symbolized[:exit_status],
+            signal: symbolized[:signal],
+            execution_began: symbolized.fetch(:execution_began, true),
+            stdout_excerpt: symbolized[:stdout_excerpt],
+            stderr_excerpt: symbolized[:stderr_excerpt]
+          )
+        end
+
+        # True when the provider process was spawned and its final state is not
+        # a confirmed successful completion. Such sessions may have performed
+        # side effects; callers must not replay them automatically.
+        def uncertain_execution?
+          execution_began
+        end
+
+        # First bounded diagnostic line from the captured streams, for
+        # actionable terminal messages. Prefers stderr; falls back to stdout.
+        # @return [String, nil]
+        def detail_line
+          source = [stderr_excerpt, stdout_excerpt].compact
+            .map { |stream| stream.lines.map(&:strip) }
+            .flatten
+            .reject(&:empty?)
+            .first.to_s
+          return nil if source.empty?
+
+          source.length > 300 ? "#{source[0, 300]}…[truncated]" : source
+        end
+
+        # Human-readable one-line summary safe for reports and error messages.
+        # @return [String]
+        def summary
+          parts = [outcome_label]
+          parts << "elapsed #{format_seconds(elapsed_seconds)}" if elapsed_seconds
+          parts << "deadline #{format_seconds(deadline_seconds)}" if deadline_seconds
+          parts << "exit #{exit_status}" unless exit_status.nil?
+          parts << "signal #{signal}" if signal
+          parts << "invocation #{invocation_id}" if invocation_id
+          parts.join(", ")
+        end
+
+        # @return [Hash] plain hash without output excerpts (for metadata surfaces)
+        def to_h
+          {
+            outcome: outcome,
+            invocation_id: invocation_id,
+            provider_name: provider_name,
+            deadline_seconds: deadline_seconds,
+            elapsed_seconds: elapsed_seconds,
+            exit_status: exit_status,
+            signal: signal,
+            execution_began: execution_began
+          }.compact
+        end
+
+        private
+
+        def outcome_label
+          case outcome
+          when :deadline_exceeded then "deadline_exceeded"
+          when :transport_failure then "transport_failure"
+          when :nonzero_exit then "nonzero_exit"
+          when :no_response then "completed_without_final_response"
+          end
+        end
+
+        def format_seconds(value)
+          return value.to_s if value.is_a?(String)
+
+          format("%.1fs", value)
+        end
+
+        def bounded_excerpt(text)
+          return nil if text.nil?
+
+          excerpt = self.class.redact(text.to_s)
+          excerpt = "#{excerpt[0, EXCERPT_LIMIT]}…[truncated]" if excerpt.length > EXCERPT_LIMIT
+          excerpt.freeze
+        end
+      end
+    end
+  end
+end

data/lib/ace/llm/molecules/fallback_orchestrator.rb

@@ -22,6 +22,8 @@ module Ace
           @visited_providers = Set.new
           @start_time = nil
           @last_failure_terminal = false
+          @last_execution_evidence = nil
+          @chain_aborted = false
         end
 
         # Execute a block with fallback support
@@ -35,6 +37,7 @@ module Ace
           @start_time = Time.now
           @primary_provider = primary_provider
           @visited_providers.clear
+          @chain_aborted = false
 
           # If fallback disabled, just execute with primary
           return yield(get_client(primary_provider, registry), primary_provider) if @config.disabled?
@@ -43,6 +46,7 @@ module Ace
           result = try_provider_with_retry(primary_provider, registry) do |client, provider_name|
             yield client, provider_name
           end
+          raise_incomplete_execution_error if @chain_aborted
           return result if result
 
           # Try fallback providers in order (per-provider chain or default)
@@ -61,6 +65,7 @@ module Ace
             result = try_provider_with_retry(fallback_provider, registry) do |client, provider_name|
               yield client, provider_name
             end
+            raise_incomplete_execution_error if @chain_aborted
             return result if result
           end
 
@@ -88,27 +93,53 @@ module Ace
             raise if error.is_a?(Ace::LLM::ConfigurationError) && provider_name != @primary_provider
             last_error = error
 
-            # Handle the error - returns :retry or :stop_and_fallback
+            # Handle the error - returns :retry, :stop_and_fallback, or :abort_chain
             action = handle_error(error, provider_name, attempts)
 
             if action == :retry
               attempts += 1
               next
-            else # :stop_and_fallback
+            else # :stop_and_fallback or :abort_chain
               return nil
             end
           end
         end
 
+        # Raise the terminal error for a chain aborted by an incomplete
+        # execution. Carries the structured evidence so downstream consumers
+        # (E2E runner, reviewers) can reconcile the session without guessing.
+        def raise_incomplete_execution_error
+          evidence = @last_execution_evidence
+          message = +"Provider execution incomplete; remaining providers were not tried to avoid replaying CLI side effects."
+          message << " Evidence: #{evidence.summary}." if evidence
+          if evidence && (detail = evidence.detail_line)
+            message << " Detail: #{detail}"
+          end
+          message << " Tried: #{@visited_providers.to_a.join(", ")}."
+          message << " Reconcile the session manually before rerunning this work."
+          error = Ace::LLM::ProviderError.new(message)
+          error.execution_evidence = evidence if evidence
+          raise error
+        end
+
         # Handle error and determine retry/fallback strategy
         # @param error [Exception] The error that occurred
         # @param provider_name [String] Provider name
         # @param attempts [Integer] Current attempt number
-        # @return [Symbol] :retry to retry, :stop_and_fallback to move to next provider
+        # @return [Symbol] :retry to retry, :stop_and_fallback to move to next provider, :abort_chain to stop entirely
         def handle_error(error, provider_name, attempts)
           classification = Atoms::ErrorClassifier.classify(error)
 
           case classification
+          when Atoms::ErrorClassifier::EXECUTION_INCOMPLETE
+            # The provider process already ran; its session ended without a
+            # confirmed completion. Retrying or falling back would replay
+            # whatever side effects the session performed.
+            @last_failure_terminal = true
+            @last_execution_evidence = Atoms::ErrorClassifier.execution_evidence_for(error)
+            @chain_aborted = true
+            report_status("⚠ #{provider_name} execution incomplete (#{@last_execution_evidence&.summary}); not retrying or falling back to avoid replaying side effects")
+            :abort_chain
           when Atoms::ErrorClassifier::SKIP_TO_NEXT
             @last_failure_terminal = false
             report_status("⚠ #{provider_name} authentication failed, skipping...")
@@ -196,13 +227,16 @@ module Ace
         def build_exhaustion_error_message
           providers_tried = @visited_providers.to_a.join(", ")
 
-          msg = "All configured providers unavailable. "
-          msg += "Tried: #{providers_tried}. "
-          msg += "\nTry:\n"
-          msg += "  - Check provider status pages\n"
-          msg += "  - Configure additional providers\n"
-          msg += "  - Retry in a few minutes\n"
-          msg += "  - Run with --debug for detailed errors"
+          msg = +"All configured providers unavailable. "
+          msg << "Tried: #{providers_tried}. "
+          if (evidence = @last_execution_evidence)
+            msg << "\nLast execution evidence: #{evidence.summary}. "
+          end
+          msg << "\nTry:\n"
+          msg << "  - Check provider status pages\n"
+          msg << "  - Configure additional providers\n"
+          msg << "  - Retry in a few minutes\n"
+          msg << "  - Run with --debug for detailed errors"
           msg
         end
 

data/lib/ace/llm/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module LLM
-    VERSION = "0.41.1"
+    VERSION = "0.42.0"
   end
 end

data/lib/ace/llm.rb

@@ -18,6 +18,7 @@ require_relative "llm/atoms/http_client"
 require_relative "llm/atoms/xdg_directory_resolver"
 require_relative "llm/atoms/error_classifier"
 
+require_relative "llm/models/execution_evidence"
 require_relative "llm/models/fallback_config"
 require_relative "llm/models/role_config"
 
@@ -51,7 +52,15 @@ require_relative "llm/cli"
 module Ace
   module LLM
     class Error < StandardError; end
-    class ProviderError < Error; end
+
+    # Provider failure carrying optional structured execution evidence
+    # (Ace::LLM::Models::ExecutionEvidence) about how the provider session
+    # actually ended. Evidence is attached at the subprocess boundary; absence
+    # keeps legacy message-based classification behavior.
+    class ProviderError < Error
+      attr_accessor :execution_evidence
+    end
+
     class ConfigurationError < Error; end
     class AuthenticationError < Error; end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-llm
 version: !ruby/object:Gem::Version
-  version: 0.41.1
+  version: 0.42.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-09-29 00:00:00.000000000 Z
+date: 2026-09-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-cli
@@ -288,6 +288,7 @@ files:
 - lib/ace/llm/cli.rb
 - lib/ace/llm/cli/commands/query.rb
 - lib/ace/llm/configuration.rb
+- lib/ace/llm/models/execution_evidence.rb
 - lib/ace/llm/models/fallback_config.rb
 - lib/ace/llm/models/role_config.rb
 - lib/ace/llm/molecules/client_registry.rb