composable_agents 2.2.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28c6711f6b4e8807c0e62349cfd5e246bf3ed56c9c1a613d14843d5b1769477d
-  data.tar.gz: a7433cc6cc01b80eb12c1b4f0eb04c8b5391e2bd10ec88aa47608ab5d25e0f0b
+  metadata.gz: 13903597d02eeacf544613b91cf9c60de076d39ecd2f3cd22b549e8a992646aa
+  data.tar.gz: 33bfbf930e6a4e43d87efadecbc1efc8a4ccf8ba29f804757b53c281d1db702f
 SHA512:
-  metadata.gz: dcffae4c60bfb6c5424cc41134ab5466e15c1f3a0b2580e4cef7d9d6c2634b5b43d721cd9f5e4bf604a968af35c02b561409cd9885f028b27bf61d7bbb2fc775
-  data.tar.gz: c83544d5ab8f321a63c87a7eb035763b12a573a3d3495e653b301c0ce71edc076838e5af84216d64395c497ec8efc7aff13be136e96c399e84b277f9cd7db0b0
+  metadata.gz: 9102890f35cef152fa02cd9ec0a2ce960b27112c4e3134865accee7c7e8b1eb8e53914ca8030543b4c35a72dfe0d7a5c07c6172d61152c90cead8bdc4183b030
+  data.tar.gz: 5e0c71dd4d3aefd7b02a1e4183151d85e7b6ea5f8eb498589e2d5dde099ff4706d10d186dfa214c665bbffb30b74eaed9c8f4b2fe0ab4e81e6f5e238ed979ff5

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+# [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
+### Patches
+
+* [feat(cline): introduce ClineError and extract MissingSkillError](https://github.com/Muriel-Salvan/composable_agents/commit/ba02df7d666c96c7cfc23a1b5a7eb92274a9e496)
+
+## Changes for cline
+### Features
+
+* [feat(cline): introduce ClineError and extract MissingSkillError](https://github.com/Muriel-Salvan/composable_agents/commit/ba02df7d666c96c7cfc23a1b5a7eb92274a9e496)
+
+# [v3.0.0](https://github.com/Muriel-Salvan/composable_agents/compare/v2.2.0...v3.0.0) (2026-11-01 12:34:56)
+
+## Global changes
+### Breaking changes
+
+* [break: add retriable artifacts mixin for auto-retry on missing outputs and remove any mixin from prompt driven agents](https://github.com/Muriel-Salvan/composable_agents/commit/76073bebe8ee247d24a3bc3279c1db822640f47a)
+
+## Changes for composable-agents
+### Features
+
+* [break: add retriable artifacts mixin for auto-retry on missing outputs and remove any mixin from prompt driven agents](https://github.com/Muriel-Salvan/composable_agents/commit/76073bebe8ee247d24a3bc3279c1db822640f47a)
+
 # [v2.2.0](https://github.com/Muriel-Salvan/composable_agents/compare/v2.1.3...v2.2.0) (2026-10-29 20:11:23)
 
 ## Global changes

data/README.md

@@ -48,12 +48,14 @@ Whether you're building a code review assistant, a document summarizer, or a mul
     - [`ComposableAgents::AiAgents::Agent < PromptDrivenAgent`](#composableagentsaiagentsagent--promptdrivenagent)
     - [`ComposableAgents::Cline::Agent < PromptDrivenAgent`](#composableagentsclineagent--promptdrivenagent)
     - [`ComposableAgents::Cline::MissingSkillError < RuntimeError`](#composableagentsclinemissingskillerror--runtimeerror)
+    - [`ComposableAgents::Cline::ClineError < RuntimeError`](#composableagentsclineerror--runtimeerror)
   - [Mixins](#mixins)
     - [`ComposableAgents::Logger < ::Logger`](#composableagentslogger--logger)
     - [`ComposableAgents::Mixins::Resumable`](#composableagentsmixinsresumable)
     - [`ComposableAgents::Mixins::UserInteraction`](#composableagentsmixinsuserinteraction)
     - [`ComposableAgents::Mixins::ArtifactContract`](#composableagentsmixinsartifactcontract)
     - [`ComposableAgents::Mixins::Retriable`](#composableagentsmixinsretriable)
+    - [`ComposableAgents::Mixins::RetriableArtifacts`](#composableagentsmixinsretriableartifacts)
   - [Additional notes](#additional-notes)
 - [Documentation](#documentation)
 - [How it works](#how-it-works)
@@ -205,6 +207,7 @@ itinerary_agent = ComposableAgents::Cline::Agent.new(
 - 📦 **Typed artifact contracts** — Define and validate input/output schemas with descriptions, optional flags, and types (`:text`, `:markdown`, `:json`). The framework raises clear `MissingInputArtifactError`, `MissingOutputArtifactError`, or `ArtifactTypeError` on violations.
 - 💾 **Resumable execution** — Persist step-by-step state to disk (via the `Resumable` mixin). Interrupted runs can be resumed seamlessly — previously completed steps are skipped, saving time and API costs.
 - 🔁 **Conditional retries** — Wrap an agent's `#run` with the `Retriable` mixin to retry on transient failures. Register condition procs via `#retry_on` that receive the agent and any raised exception (or `nil`) and return a policy hash (optional `:wait_secs`, optional `:modifier`) to wait-and-retry, or `nil` to skip. Unhandled exceptions are re-raised when no policy applies.
+- 🔁 **Automatic artifact retry* — Prepend the RetriableArtifacts mixin to a PromptDrivenAgent subclass to automatically re-run when output artifacts declared in contracts are missing or in error. Configurable via `artifacts_errors_max_retries` (default: 3); raises `ArtifactsErrorsMaxRetriesExceededError` when the limit is exceeded.
 - 🗣️ **User interaction** — Agents can ask users clarifying questions mid-execution. Works out of the box via the terminal, or through an `ai-agents` tool integration for LLM-controlled workflows.
 - 📋 **Automatic conversation tracking** — Every prompt and response is automatically recorded with timestamps in a structured `conversation` store, ready for debugging or replay.
 - ⚙️ **Flexible instruction system** — Use raw text, structured ordered-lists, or a mix of both to define agent instructions, rendered consistently by the chosen strategy.
@@ -361,6 +364,11 @@ The project is a Ruby library (not a CLI) — users install the gem and use its
 - **Description:** Raised by `Cline::Agent` when a referenced skill is not found in the global or project Cline configuration.
 - **Full documentation:** [cline/agent.rb on GitHub](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/cline/agent.rb)
 
+#### `ComposableAgents::Cline::ClineError < RuntimeError`
+
+- **Description:** Raised by `Cline::Agent` when a Cline CLI run fails.
+- **Full documentation:** [cline/cline_error.rb on GitHub](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/cline/cline_error.rb)
+
 ---
 
 ### Mixins
@@ -480,6 +488,34 @@ Mixins are `prepend`-ed into an agent class to add specific capabilities.
   ```
 - **Full documentation:** [Mixins::Retriable on RubyDoc](https://www.rubydoc.info/gems/composable_agents/ComposableAgents/Mixins/Retriable) | [retriable.rb on GitHub](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/retriable.rb)
 
+
+#### `ComposableAgents::Mixins::RetriableArtifacts`
+
+- **Description:** Automatically retries the run when output artifacts declared in contracts are missing or in error on prompt-driven agents. Requires both the ArtifactContract and Retriable mixins to be prepended, and must be prepended on an agent descending from PromptDrivenAgent.
+- **Public methods:**
+  - `#initialize(*args, artifacts_errors_max_retries: 3, **kwargs)` — Registers a retry policy that re-executes the run with a prompt asking for missing artifacts when output artifacts are missing or in error. The artifacts_errors_max_retries parameter (default: 3) sets the maximum number of retries before raising ArtifactsErrorsMaxRetriesExceededError.
+- **Usage example:**
+  ```ruby
+  class MyAgent < ComposableAgents::PromptDrivenAgent
+    prepend ComposableAgents::Mixins::ArtifactContract
+    prepend ComposableAgents::Mixins::Retriable
+    prepend ComposableAgents::Mixins::RetriableArtifacts
+
+    def output_artifacts_contracts
+      { result: "Final result", logs: "Execution logs" }
+    end
+
+    def run(**inputs)
+      # Processing logic that may produce incomplete output artifacts
+      super
+    end
+  end
+
+  agent = MyAgent.new(artifacts_errors_max_retries: 3)
+  agent.run  # Automatically retries if result or logs are missing or in error
+  ```
+- **Raises:** ArtifactsErrorsMaxRetriesExceededError when the maximum number of retries is exceeded.
+
 ---
 
 ### Additional notes
@@ -680,7 +716,7 @@ npm install node-pty
 │       ├── instructions.rb       # Instruction system
 │       ├── ai_agents/            # ai-agents backend
 │       ├── cline/                # cline-rb backend
-│       ├── mixins/               # Resumable, ArtifactContract, UserInteraction, Logger
+│       ├── mixins/               # ArtifactContract, Logger, Resumable, Retriable, RetriableArtifacts, UserInteraction
 │       ├── prompt_rendering_strategy/ # Markdown & MarkdownHeavy strategies
 │       └── utils/                # Markdown utilities
 ├── spec/                         # Test suite

data/TODO.md

@@ -1,5 +1,4 @@
 * 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.
-* Use the Retriable mixin with ArtifactContract.
 * 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/artifacts_errors_max_retries_exceeded_error.rb

@@ -0,0 +1,6 @@
+module ComposableAgents
+  # Custom exception raised when the maximum number of retries for output artifacts
+  # errors (missing or in error) is exceeded and the run cannot succeed.
+  class ArtifactsErrorsMaxRetriesExceededError < StandardError
+  end
+end

data/lib/composable_agents/cline/agent.rb

@@ -3,10 +3,6 @@ require 'cline'
 module ComposableAgents
   # All agents from this module work with the awesome cline-rb Rubygem
   module Cline
-    # Missin skill error
-    class MissingSkillError < RuntimeError
-    end
-
     # Agent implementation that uses an ai-agent's AgentRunner.
     # This agent publishes the following run information:
     # - usage [Hash] Cumulative usage of the API requests (cost and tokens) made during the run.
@@ -23,8 +19,6 @@ module ComposableAgents
     class Agent < PromptDrivenAgent
       # @!group Public API
 
-      prepend Mixins::ArtifactContract
-
       # Initialize a new agent that uses the Cline CLI in a dedicated config
       #
       # @param strategy [Module] The prompt rendering strategy
@@ -170,7 +164,7 @@ module ComposableAgents
           end,
           **@cli_options
         )
-        raise "Error: #{extract_error_message(result[:error])}".strip if result[:error]
+        raise ClineError, "Error: #{extract_error_message(result[:error])}".strip if result[:error]
 
         # Keep the context in case we need to resume it
         if cline_cli.session&.messages

data/lib/composable_agents/cline/cline_error.rb

@@ -0,0 +1,7 @@
+module ComposableAgents
+  module Cline
+    # Error raised when a Cline CLI run fails.
+    class ClineError < RuntimeError
+    end
+  end
+end

data/lib/composable_agents/cline/missing_skill_error.rb

@@ -0,0 +1,7 @@
+module ComposableAgents
+  module Cline
+    # Missing skill error
+    class MissingSkillError < RuntimeError
+    end
+  end
+end

data/lib/composable_agents/mixins/artifact_contract.rb

@@ -64,6 +64,15 @@ module ComposableAgents
 
       private
 
+      # Restrict the output artifacts errors that should raise an {OutputArtifactsError} at the end of a run
+      #   to only those concerning artifacts defined in the output artifacts contracts.
+      # Errors on artifacts that are not part of the contracts are ignored.
+      #
+      # @return [Hash{Symbol => String}] The output artifacts errors that should raise, per artifact name
+      def output_artifacts_errors_to_raise
+        (defined?(super) ? super : {}).slice(*normalized_output_artifacts_contracts.keys)
+      end
+
       # Define input artifacts contracts
       #
       # @return [Hash{Symbol => Object}] Set of input artifacts contract, per artifact name

data/lib/composable_agents/mixins/retriable_artifacts.rb

@@ -0,0 +1,92 @@
+module ComposableAgents
+  module Mixins
+    # Mixin adding automatic retry of the run when output artifacts are missing on prompt-driven agents.
+    # This mixin requires the following mixins to be prepended:
+    # - The {ArtifactContract} mixin.
+    # - The {Retriable} mixin.
+    # This mixin requires to be prepended on an agent descending from {PromptDrivenAgent}.
+    #
+    # When prepended to an agent descending from PromptDrivenAgent, the run method will
+    # automatically re-execute until all expected output artifacts have been provided.
+    #
+    # On retry, the overridden #run method uses a prompt asking for missing artifacts
+    # as +user_instructions+ instead of the original one.
+    # When the run raised an {OutputArtifactsError}, artifacts having errors are also
+    # included in the prompt, taken from the exception data.
+    module RetriableArtifacts
+      # Initialize a new agent with the retry-on-missing-artifacts policy registered.
+      #
+      # @param artifacts_errors_max_retries [Integer] Maximum number of retries when output
+      #   artifacts are missing or in error. Defaults to 3. When the number of retries
+      #   exceeds this value, a {ArtifactsErrorsMaxRetriesExceededError} is raised.
+      # @param args [Array] Arguments passed to the parent initializer
+      # @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
+        max_retries = artifacts_errors_max_retries
+        artifacts_errors_retries = 0
+        last_artifact_keys = nil
+        retry_on(
+          proc do |_agent, exception|
+            output_artifacts_errors = exception.is_a?(OutputArtifactsError) ? exception.output_artifacts_errors : {}
+            missing = missing_artifacts(output_artifacts_errors)
+            artifact_keys = missing.keys
+
+            # Reset counter when the set of artifacts needing retry changes between iterations
+            if artifact_keys != last_artifact_keys
+              artifacts_errors_retries = 0
+              last_artifact_keys = artifact_keys
+            end
+
+            # If no artifacts need retry, return nil (no retry)
+            if artifact_keys.empty?
+              nil
+            elsif artifacts_errors_retries >= max_retries
+              artifacts_errors_retries = 0
+              last_artifact_keys = []
+              raise ArtifactsErrorsMaxRetriesExceededError,
+                    "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) } }
+            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.
+      #
+      # @param output_artifacts_errors [Hash{Symbol => String}] Artifacts having errors, per artifact name,
+      #   as given by the {OutputArtifactsError} raised by the run (or empty if none).
+      # @return [Hash{Symbol => Hash{Symbol => Object}}] Missing artifacts, per artifact name.
+      def missing_artifacts(output_artifacts_errors)
+        normalized_output_artifacts_contracts
+          .reject { |artifact_name, _artifact_description| @output_artifacts.key?(artifact_name) }
+          .to_h do |artifact_name, artifact_description|
+            [
+              artifact_name,
+              artifact_description.merge(output_artifacts_errors[artifact_name] ? { error: output_artifacts_errors[artifact_name] } : {})
+            ]
+          end
+      end
+    end
+  end
+end

data/lib/composable_agents/output_artifacts_error.rb

@@ -0,0 +1,16 @@
+module ComposableAgents
+  # Custom exception raised when output artifacts have errors.
+  # The whole output_artifacts_errors structure is embedded in the exception.
+  class OutputArtifactsError < StandardError
+    # @return [Hash{Symbol => String}] The list of artifacts in error, with their corresponding error message.
+    attr_reader :output_artifacts_errors
+
+    # Initialize a new OutputArtifactsError with the errors hash.
+    #
+    # @param output_artifacts_errors [Hash] Hash of artifact names to errors
+    def initialize(output_artifacts_errors)
+      @output_artifacts_errors = output_artifacts_errors
+      super("Output artifacts errors: #{output_artifacts_errors.inspect}")
+    end
+  end
+end

data/lib/composable_agents/prompt_driven_agent.rb

@@ -59,6 +59,8 @@ module ComposableAgents
       @system_instructions = system_instructions
       @constraints = constraints
       @conversation = []
+      @output_artifacts = {}
+      @output_artifacts_errors = {}
     end
 
     # Execute the agent to generate some output artifacts based on some input artifacts.
@@ -70,29 +72,14 @@ module ComposableAgents
     def run(user_instructions: nil, **input_artifacts)
       super
       @input_artifacts = input_artifacts
-      @output_artifacts = {}
-      @output_artifacts_errors = {}
       @system_prompt = render_system_prompt(render_instructions(@system_instructions))
       logger.debug "System prompt: #{@system_prompt}"
+      # TODO: Merge converse and prompt directly here. No need for this extra complexity now that Retriable has been moved out.
       converse(user_instructions, input_artifacts: @input_artifacts, author: 'User')
-      if respond_to?(:normalized_output_artifacts_contracts, true)
-        # We know which output artifacts we are expecting.
-        # Therefore check if some are missing and prompt again if that's the case.
-        # TODO: Implement a max number of retries and throw an exception if it exceeds.
-        loop do
-          missing_artifacts = normalized_output_artifacts_contracts
-            .reject { |artifact_name, _artifact_description| @output_artifacts.key?(artifact_name) }
-            .to_h do |artifact_name, artifact_description|
-              [
-                artifact_name,
-                artifact_description.merge(@output_artifacts_errors[artifact_name] ? { error: @output_artifacts_errors[artifact_name] } : {})
-              ]
-            end
-          break if missing_artifacts.empty?
-
-          converse(missing_output_user_instructions(missing_artifacts))
-        end
-      end
+      # Raise an exception if some output artifacts have errors.
+      output_artifacts_errors = output_artifacts_errors_to_raise
+      raise OutputArtifactsError, output_artifacts_errors unless output_artifacts_errors.empty?
+
       @output_artifacts
     end
 
@@ -168,6 +155,15 @@ module ComposableAgents
 
     private
 
+    # Get the output artifacts errors that should raise an {OutputArtifactsError} at the end of a run.
+    # By default, all the errors that were reported during the run should raise.
+    # This is a hook that other mixins can override to restrict the errors that should raise.
+    #
+    # @return [Hash{Symbol => String}] The output artifacts errors that should raise, per artifact name
+    def output_artifacts_errors_to_raise
+      @output_artifacts_errors
+    end
+
     # Render instructions using the prompt rendering strategy.
     # Returns nil if instructions is nil.
     #

data/lib/composable_agents/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: composable_agents
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 3.1.0
 platform: ruby
 authors:
 - Muriel Salvan
@@ -80,7 +80,10 @@ files:
 - lib/composable_agents/ai_agents/tools/base_tool.rb
 - lib/composable_agents/ai_agents/tools/create_artifact_tool.rb
 - lib/composable_agents/ai_agents/tools/get_artifact_tool.rb
+- lib/composable_agents/artifacts_errors_max_retries_exceeded_error.rb
 - lib/composable_agents/cline/agent.rb
+- lib/composable_agents/cline/cline_error.rb
+- lib/composable_agents/cline/missing_skill_error.rb
 - lib/composable_agents/instructions.rb
 - lib/composable_agents/logger.rb
 - lib/composable_agents/logger/tagged.rb
@@ -88,7 +91,9 @@ files:
 - lib/composable_agents/mixins/artifact_contract.rb
 - lib/composable_agents/mixins/resumable.rb
 - lib/composable_agents/mixins/retriable.rb
+- lib/composable_agents/mixins/retriable_artifacts.rb
 - lib/composable_agents/mixins/user_interaction.rb
+- lib/composable_agents/output_artifacts_error.rb
 - lib/composable_agents/prompt_driven_agent.rb
 - lib/composable_agents/prompt_rendering_strategy/markdown.rb
 - lib/composable_agents/prompt_rendering_strategy/markdown_heavy.rb