composable_agents 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aee730a3031c19e5b24bdd00a7a1fea08e590ff99916b61d4d20caa1c6f5d6db
-  data.tar.gz: 38195f2c530d077d429d5e3c253c96d0b41d4660b159aea68cf610fb26f3c10b
+  metadata.gz: 1f49d4d1885ee0ce3abc08d156910295fa39b602450f68588259473acd62d30a
+  data.tar.gz: 715281f951f66e05ca81b6a237b03c690ca319d9f6ee093471db560fd03ce441
 SHA512:
-  metadata.gz: bc150e2714463ef82f7dbdac5a90716b06643728ea839c1c8b60643d2175730efdfbe10ee855d5536dc268a654678a470757e16e3a3fea169bbb44dffde6e1cb
-  data.tar.gz: 992a6ef86a797cdd5110a0398e22a223d93e0bb7c0b4ec531ec25ec98466edc99cf20b3521f8118194cd32ecb1c02d1de898ea0ad5c8a9a1f5f92ea31a4345e4
+  metadata.gz: ac0d9cbbfd7a3e6c6155e7f3276264b7c86c1ed6f68ebab6742665b25d44d14c99d544e07ff2ca22dcf59d68af6dd8064a1612c727fc39aa4318ad2de1a28c8d
+  data.tar.gz: 7bdb521e572cfc1e75f108a4d2d46aaadd7ba409e7e2cebddef4e0062b6db2e83cb0ade32429e7b7d21651061ac56786201142952c7a339cf57c23870132ae2a

data/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [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

data/README.md

@@ -521,6 +521,38 @@ When a proc returns a policy, the agent waits `wait_secs` seconds, applies the `
 
 ---
 
+#### `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/`.
@@ -719,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_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

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.2.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.2.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