composable_agents 3.1.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13903597d02eeacf544613b91cf9c60de076d39ecd2f3cd22b549e8a992646aa
-  data.tar.gz: 33bfbf930e6a4e43d87efadecbc1efc8a4ccf8ba29f804757b53c281d1db702f
+  metadata.gz: 1f49d4d1885ee0ce3abc08d156910295fa39b602450f68588259473acd62d30a
+  data.tar.gz: 715281f951f66e05ca81b6a237b03c690ca319d9f6ee093471db560fd03ce441
 SHA512:
-  metadata.gz: 9102890f35cef152fa02cd9ec0a2ce960b27112c4e3134865accee7c7e8b1eb8e53914ca8030543b4c35a72dfe0d7a5c07c6172d61152c90cead8bdc4183b030
-  data.tar.gz: 5e0c71dd4d3aefd7b02a1e4183151d85e7b6ea5f8eb498589e2d5dde099ff4706d10d186dfa214c665bbffb30b74eaed9c8f4b2fe0ab4e81e6f5e238ed979ff5
+  metadata.gz: ac0d9cbbfd7a3e6c6155e7f3276264b7c86c1ed6f68ebab6742665b25d44d14c99d544e07ff2ca22dcf59d68af6dd8064a1612c727fc39aa4318ad2de1a28c8d
+  data.tar.gz: 7bdb521e572cfc1e75f108a4d2d46aaadd7ba409e7e2cebddef4e0062b6db2e83cb0ade32429e7b7d21651061ac56786201142952c7a339cf57c23870132ae2a

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+# [v3.3.0](https://github.com/Muriel-Salvan/composable_agents/compare/v3.2.0...v3.3.0) (2026-11-02 17:21:04)
+
+## Global changes
+### Patches
+
+* [feat(cline): add RetriableCline mixin](https://github.com/Muriel-Salvan/composable_agents/commit/66daaa29898faf17026661042484320d82811c8a)
+
+## Changes for cline
+### Features
+
+* [feat(cline): add RetriableCline mixin](https://github.com/Muriel-Salvan/composable_agents/commit/66daaa29898faf17026661042484320d82811c8a)
+
+# [v3.2.0](https://github.com/Muriel-Salvan/composable_agents/compare/v3.1.0...v3.2.0) (2026-11-02 16:54:36)
+
+## Global changes
+### Patches
+
+* [feat(Retriable): enhance retry policy options with new_input_artifacts, altering retried input artifacts](https://github.com/Muriel-Salvan/composable_agents/commit/e4ee0fe4105bdddb87670817006aedee6a7f3840)
+
+## Changes for Retriable
+### Features
+
+* [feat(Retriable): enhance retry policy options with new_input_artifacts, altering retried input artifacts](https://github.com/Muriel-Salvan/composable_agents/commit/e4ee0fe4105bdddb87670817006aedee6a7f3840)
+
 # [v3.1.0](https://github.com/Muriel-Salvan/composable_agents/compare/v3.0.0...v3.1.0) (2026-11-01 13:55:18)
 
 ## Global changes

data/README.md

@@ -463,11 +463,14 @@ Mixins are `prepend`-ed into an agent class to add specific capabilities.
 
 #### `ComposableAgents::Mixins::Retriable`
 
-- **Description:** Adds conditional retry capabilities to agents. Retry condition procs are registered with `#retry_on` (or `#with_retry_on` for temporary activation) and are evaluated at the end of each run. A proc receives the agent instance and the exception raised by `run` (or `nil` if none) and returns either `nil` (no retry) or a policy hash with `:wait_secs` and optional `:modifier` keys. When a proc returns a policy, the agent waits `wait_secs` seconds, optionally calls the policy's `modifier`, and re-runs. If `run` raised an exception and no proc returned a retry policy, the exception is re-raised to the caller.
+- **Description:** Adds conditional retry capabilities to agents. Retry condition procs are registered with `#retry_on` (or `#with_retry_on` for temporary activation) and are evaluated at the end of each run. A proc receives the agent instance and the exception raised by `run` (or `nil` if none) and returns either `nil` (no retry) or a policy hash with optional keys to describe the policy:
+  - `:wait_secs` — Wait time in seconds before retrying (defaults to 0).
+  - `:modifier` — Proc called with the agent before retrying ( defaults to doing nothing).
+  - `:new_input_artifacts` — Hash of input artifacts to add to the retried run (defaults to `{}`).
+When a proc returns a policy, the agent waits `wait_secs` seconds, applies the `modifier` proc (if any), merges the `new_input_artifacts` into the retry input, and re-runs. If `run` raised an exception and no proc returned a retry policy, the exception is re-raised to the caller.
 - **Public methods:**
-  - `#retry_on(proc)` — Register a retry condition proc. Returns `self` so calls can be chained.
+  - `#retry_on(proc)` — Register a retry condition proc.
   - `#with_retry_on(proc, &block)` — Register a retry proc for the duration of a block, then unregister it when the block returns (even if it raises).
-  - policy hash — Configuration with optional `:wait_secs` (seconds to wait before retrying, defaults to 0) and optional `:modifier` (proc called with the agent before retrying).
 - **Usage example:**
   ```ruby
   class MyAgent < ComposableAgents::Agent
@@ -518,6 +521,38 @@ Mixins are `prepend`-ed into an agent class to add specific capabilities.
 
 ---
 
+#### `ComposableAgents::Mixins::RetriableCline`
+
+- **Description:** Automatically retries the run when Cline raises errors (such as `UnexpectedExitStatusError` or `UnexpectedInteractiveSessionError`) using exponential backoff with jitter. Requires the `Retriable` mixin to be prepended first, and must be prepended on an agent descending from `ComposableAgents::Cline::Agent`.
+
+- **Public methods:**
+  - `#initialize(*args, cline_errors_max_retries: 3, cline_errors_retry_initial_delay_secs: 5, cline_errors_retry_backoff_factor: 2, cline_errors_retry_max_delay_secs: 60, cline_errors_retry_jitter: 0.1, **kwargs)` — Registers a retry policy that re-executes the run with exponential backoff when Cline errors occur. Configuration options include:
+    - `cline_errors_max_retries`: Maximum number of retries (default: 3)
+    - `cline_errors_retry_initial_delay_secs`: Initial delay in seconds before first retry (default: 5)
+    - `cline_errors_retry_backoff_factor`: Multiplier for each subsequent retry (default: 2)
+    - `cline_errors_retry_max_delay_secs`: Maximum delay between retries (default: 60)
+    - `cline_errors_retry_jitter`: Amount of random jitter to add (default: 0.1 = 10%)
+  - `#run(user_instructions: nil, **input_artifacts)` — Re-executes the run, using stored user instructions from interactive session errors if applicable.
+
+- **Usage example:**
+  ```ruby
+  class MyClineAgent < ComposableAgents::Cline::Agent
+    prepend ComposableAgents::Mixins::Retriable
+    prepend ComposableAgents::Mixins::RetriableCline
+
+    def run(**inputs)
+      super
+    end
+  end
+
+  agent = MyClineAgent.new(cline_errors_max_retries: 3, cline_errors_retry_initial_delay_secs: 2)
+  agent.run  # Automatically retries on Cline errors with exponential backoff
+  ```
+
+- **Raises:** Various Cline error classes (e.g., `ComposableAgents::Cline::ClineError`, `::Cline::Cli::UnexpectedExitStatusError`, `::Cline::Cli::UnexpectedInteractiveSessionError`) when the maximum number of retries is exceeded.
+
+---
+
 ### Additional notes
 
 - **No executables / CLI** — This gem is a library only; there are no scripts in `bin/`.
@@ -716,7 +751,7 @@ npm install node-pty
 │       ├── instructions.rb       # Instruction system
 │       ├── ai_agents/            # ai-agents backend
 │       ├── cline/                # cline-rb backend
-│       ├── mixins/               # ArtifactContract, Logger, Resumable, Retriable, RetriableArtifacts, UserInteraction
+│       ├── mixins/               # ArtifactContract, Logger, Resumable, Retriable, RetriableArtifacts, RetriableCline, UserInteraction
 │       ├── prompt_rendering_strategy/ # Markdown & MarkdownHeavy strategies
 │       └── utils/                # Markdown utilities
 ├── spec/                         # Test suite

data/TODO.md

@@ -1,4 +1,5 @@
-* Add the Retriable mixin to Cline::Agent with proper methods or config to define fallback models or changes in case of errors, with exponential waits.
+* Add a new mixin for Cline::Agent with proper methods or config to define retries in case of errors, with exponential waits.
+* Add a new retry mixin for Cline::Agent with proper methods or config to define retries in case of errors and 429 issues to define fallback models in case of errors, with exponential waits (reuse code from the RetriableCline mixin).
 * Add a way to detect infinite loops in agents and act on it (maybe a mixin looking at prompts/messages).
 * Add a way to kill an agent run on a given timeout (generic mixin).
 * Check Rubocop-rspec exceptions and try to remove them.

data/lib/composable_agents/mixins/retriable.rb

@@ -17,14 +17,13 @@ module ComposableAgents
     # * Each registered proc is kept in an internal array, in registration order.
     # * A proc receives the agent's instance and the exception raised by `run`
     #   (or `nil` if none) and returns either `nil` (no retry) or a policy hash
-    #   with optional `:wait_secs` and optional `:modifier` keys.
+    #   (see Retriable#retry_on).
     # * The run method is wrapped: it calls the original run, then evaluates the
     #   registered procs in order until one returns a non-nil policy hash.
     # * If `run` raised an exception and no proc returned a non-nil policy hash,
     #   the exception is re-raised to the caller.
     # * If a proc decides to retry: wait for `wait_secs` seconds, then call the
-    #   `modifier` proc (if any), then call run again.
-    #
+    #   `modifier` proc (if any), merge the `new_input_artifacts` into the retry input, and call run again.
     module Retriable
       # @!group Public API
 
@@ -41,8 +40,9 @@ module ComposableAgents
       #   - param exception [Exception, nil] The exception that was raised by the run, or nil if none.
       #   - result [Hash\\{Symbol => Object}] Definition of the retry policy, with optional properties:
       #     - wait_secs [Integer, Float] Wait time in seconds before retrying (defaults to 0).
-      #     - modifier [Proc] Code called to modify the agent's state before retrying (defaults to doing nothing).
+      #     - modifier [#call(agent)] Code called to modify the agent's state before retrying (defaults to doing nothing).
       #       - param agent [Agent] The agent for which the retry is considered.
+      #     - new_input_artifacts [Hash\\{Symbol => Object}] New input artifacts that need to be added to the retried run (defaults to {}).
       # @return [self]
       def retry_on(proc)
         retry_policies << proc
@@ -78,12 +78,13 @@ module ComposableAgents
       # @param input_artifacts [Hash{Symbol => Object}] input artifacts
       # @return [Hash{Symbol => Object}] output artifacts from the last run
       def run(**input_artifacts)
+        retry_input_artifacts = input_artifacts.dup
         output_artifacts = nil
         retry_index = 0
         loop do
           exception = nil
           begin
-            output_artifacts = super
+            output_artifacts = super(**retry_input_artifacts)
           rescue StandardError => e
             exception = e
           end
@@ -98,6 +99,7 @@ module ComposableAgents
             logger.debug "Retry ##{retry_index}: re-running in #{wait_secs}s#{" (exception #{exception})" if exception}"
             sleep(wait_secs) if wait_secs.positive?
             policy[:modifier]&.call(self)
+            retry_input_artifacts.merge!(policy[:new_input_artifacts] || {})
           else
             raise exception if exception
 

data/lib/composable_agents/mixins/retriable_artifacts.rb

@@ -23,7 +23,7 @@
       # @param kwargs [Hash] Keyword arguments passed to the parent initializer
       def initialize(*args, artifacts_errors_max_retries: 3, **kwargs)
         super(*args, **kwargs)
-        @overridden_user_instructions = nil
+        @retriable_artifacts_user_instructions = nil
         max_retries = artifacts_errors_max_retries
         artifacts_errors_retries = 0
         last_artifact_keys = nil
@@ -49,27 +49,12 @@
                     "Maximum number of retries (#{max_retries}) exceeded. Missing or errored artifacts: #{artifact_keys.join(', ')}"
             else
               artifacts_errors_retries += 1
-              { modifier: proc { @overridden_user_instructions = missing_output_user_instructions(missing) } }
+              { new_input_artifacts: { user_instructions: missing_output_user_instructions(missing) } }
             end
           end
         )
       end
 
-      # Execute the agent to generate some output artifacts based on some input artifacts.
-      # On retry, uses +@overridden_user_instructions+ (set by the retry policy's modifier)
-      # instead of the original +user_instructions+.
-      #
-      # @param user_instructions [Object, nil] Instructions for the user prompt, that will be rendered.
-      # @param input_artifacts [Hash{Symbol => Object}] The input artifacts content, per artifact name
-      # @return [Hash{Symbol => Object}] The output artifacts
-      def run(user_instructions: nil, **input_artifacts)
-        if @overridden_user_instructions
-          user_instructions = @overridden_user_instructions
-          @overridden_user_instructions = nil
-        end
-        super
-      end
-
       private
 
       # Compute the missing output artifacts with their descriptions and errors.

data/lib/composable_agents/mixins/retriable_cline.rb

@@ -0,0 +1,68 @@
+require 'cline'
+
+module ComposableAgents
+  module Mixins
+    # Mixin adding automatic retry of the run when Cline is raising errors.
+    # This mixin requires the following mixins to be prepended:
+    # - The {Retriable} mixin.
+    # This mixin requires to be prepended on an agent descending from {ComposableAgents::Cline::Agent}.
+    #
+    # When prepended to an agent descending from ComposableAgents::Cline::Agent, the run method will
+    # automatically re-execute while errors are being raised, using exponential backoff with jitter.
+    module RetriableCline
+      # Constructor
+      #
+      # @param cline_errors_max_retries [Integer] Maximum number of retries for Cline errors
+      # @param cline_errors_retry_initial_delay_secs [Float] Initial delay in seconds before the first retry
+      # @param cline_errors_retry_backoff_factor [Float] Backoff multiplier for each subsequent retry
+      # @param cline_errors_retry_max_delay_secs [Float] Maximum delay in seconds between retries
+      # @param cline_errors_retry_jitter [Float] Amount of random jitter to add to the delay
+      def initialize(
+        *args,
+        cline_errors_max_retries: 3,
+        cline_errors_retry_initial_delay_secs: 5,
+        cline_errors_retry_backoff_factor: 2,
+        cline_errors_retry_max_delay_secs: 60,
+        cline_errors_retry_jitter: 0.1,
+        **kwargs
+      )
+        super(*args, **kwargs)
+        @retriable_cline_user_instructions = nil
+        max_retries = cline_errors_max_retries
+        initial_delay = cline_errors_retry_initial_delay_secs
+        backoff_factor = cline_errors_retry_backoff_factor
+        max_delay = cline_errors_retry_max_delay_secs
+        jitter = cline_errors_retry_jitter
+        retries = 0
+        retry_on(
+          proc do |_agent, exception|
+            next nil if retries >= max_retries || CLINE_ERROR_CLASSES.none? { |klass| exception.is_a?(klass) }
+
+            retries += 1
+            delay = initial_delay * (backoff_factor**(retries - 1))
+            delay *= (1 + (jitter * ((2 * rand) - 1))) if jitter.positive?
+            retry_policy = { wait_secs: delay.clamp(0, max_delay) }
+            if exception.is_a?(::Cline::Cli::UnexpectedInteractiveSessionError)
+              retry_policy[:new_input_artifacts] = { user_instructions: INTERACTIVE_SESSION_USER_INSTRUCTIONS }
+            end
+            retry_policy
+          end
+        )
+      end
+
+      # @return [Array<Class>] List of Cline error classes that trigger a retry of the run when raised by Cline.
+      CLINE_ERROR_CLASSES = [
+        ComposableAgents::Cline::ClineError,
+        ::Cline::Cli::UnexpectedExitStatusError,
+        ::Cline::Cli::UnexpectedInteractiveSessionError
+      ].freeze
+
+      # @return [String] Default user instructions used to retry a run that raised an {::Cline::Cli::UnexpectedInteractiveSessionError}.
+      INTERACTIVE_SESSION_USER_INSTRUCTIONS = <<~TEXT.freeze
+        You are not running in interactive mode, so you will not receive any input from the user.
+        If you were expecting to ask the user a question, you must find the best answer to your question by yourself
+        and proceed without user input.
+      TEXT
+    end
+  end
+end

data/lib/composable_agents/version.rb

@@ -2,5 +2,5 @@ module ComposableAgents
   # @!group Public API
 
   # Gem version
-  VERSION = '3.1.0'
+  VERSION = '3.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: composable_agents
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 3.3.0
 platform: ruby
 authors:
 - Muriel Salvan
@@ -92,6 +92,7 @@ files:
 - lib/composable_agents/mixins/resumable.rb
 - lib/composable_agents/mixins/retriable.rb
 - lib/composable_agents/mixins/retriable_artifacts.rb
+- lib/composable_agents/mixins/retriable_cline.rb
 - lib/composable_agents/mixins/user_interaction.rb
 - lib/composable_agents/output_artifacts_error.rb
 - lib/composable_agents/prompt_driven_agent.rb