composable_agents 1.0.1 → 1.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3f9996134748aa3bf3ad0893b706a99a9c4611adcf5455591ef427230cebd64f
-  data.tar.gz: 283f258cf24bf3dfca6575a0fe29f5cee5d8096de2cf0b40c73ac6060a78f76d
+  metadata.gz: 83d046d554869aa540c97465182338129f2aefbf14f92b20fc0aaf81ef54b632
+  data.tar.gz: 0b86bd8489a1b4b2f66a1ae20c33c543b055c559e07cafddc18924628a58ef01
 SHA512:
-  metadata.gz: e7009799753fdd7216b8ef26c7756da633aa17665e4ca9ae6fc4f586fcc2501c2eade1e2ab7ac906fba5ddfe42888f4317cdd1611e20649d93eb3ab624ca58bc
-  data.tar.gz: 5f374253ab859627a3c3a745f12b003e53149c3a358808990d67daef639013c0f57b3cbb6687fc2366d784937b09d932afaac893887f1d14e9a9ea3529298d3e
+  metadata.gz: 313bf41f9c1b24ce950ef3071adbf79a1433e4dea0d1b586964ef30854153c4f06e9a44ccbf852c2d798d8bd90e6bf2328f5f35beb799e433b0712250ad076c9
+  data.tar.gz: 94dfd245657963c6566b796d99bd7be1d5609d30c04b68d0ee0a6845f9b1082a33ed6494a3c0b45447120f20ef0f498d064ad3c89e5d7be09f873554de1bb0f4

data/CHANGELOG.md

@@ -1,3 +1,34 @@
+# [v1.1.2](https://github.com/Muriel-Salvan/composable_agents/compare/v1.1.1...v1.1.2) (2026-09-03 16:08:18)
+
+### Patches
+
+* [ci: add RubyGems credential configuration workflow](https://github.com/Muriel-Salvan/composable_agents/commit/76219abd1356bf1fc070347a74aa4472c24b4fc6)
+
+# [v1.1.1](https://github.com/Muriel-Salvan/composable_agents/compare/v1.1.0...v1.1.1) (2026-09-03 15:35:07)
+
+### Patches
+
+* [build(deps): update ai-agents, commonmarker, and zeitwerk versions](https://github.com/Muriel-Salvan/composable_agents/commit/66fc281db2e68e6f07edcde15371a865bcf97d13)
+
+# [v1.1.0](https://github.com/Muriel-Salvan/composable_agents/compare/v1.0.1...v1.1.0) (2026-09-03 14:36:17)
+
+## Global changes
+### Patches
+
+* [docs(resumable): simplify type annotations in steps_run docs](https://github.com/Muriel-Salvan/composable_agents/commit/dc4ef8838791f0d62a65646b46cd2fc9600027c6)
+* [feat: record error status and message for failed steps](https://github.com/Muriel-Salvan/composable_agents/commit/db54a74e92381012db19a5a00bb02b86c0885422)
+* [feat(resumable): add created_at timestamp to step run tracking](https://github.com/Muriel-Salvan/composable_agents/commit/5158c186003ec8bbcde5fb5a10fad026f94f849c)
+* [refactor: track step index in steps_run hierarchy](https://github.com/Muriel-Salvan/composable_agents/commit/8c0d73c1a3abb9b762d2d09be8430480eeb5f384)
+* [[Feature(Resumable)] Implement steps_run with history of all runs.](https://github.com/Muriel-Salvan/composable_agents/commit/97e3f7477155aa6e2d3e6ee85e5389bb1d2ac70e)
+* [[Feature(Resumable)] Add status to steps_run](https://github.com/Muriel-Salvan/composable_agents/commit/2abd016de83cee43a821674e219deba1f6b79a24)
+* [feat: add steps_run hierarchy tracking to resumable mixin](https://github.com/Muriel-Salvan/composable_agents/commit/c656ea56a8ce81729075f8d98f0227c7402106e3)
+
+## Changes for Resumable
+### Features
+
+* [[Feature(Resumable)] Implement steps_run with history of all runs.](https://github.com/Muriel-Salvan/composable_agents/commit/97e3f7477155aa6e2d3e6ee85e5389bb1d2ac70e)
+* [[Feature(Resumable)] Add status to steps_run](https://github.com/Muriel-Salvan/composable_agents/commit/2abd016de83cee43a821674e219deba1f6b79a24)
+
 # [v1.0.1](https://github.com/Muriel-Salvan/composable_agents/compare/v1.0.0...v1.0.1) (2026-07-01 16:37:12)
 
 ### Patches

data/README.md

@@ -610,7 +610,7 @@ flowchart LR
     E --> F
 ```
 
-The `Resumable` mixin tracks a **hierarchical step index** (`@steps_idx`) that mirrors the nesting of `step` blocks. Each step's input/output state is saved as a JSON file. On re-execution with the same `run_id`, the framework loads the saved state instead of re-running completed steps — saving both time and API costs.
+The `Resumable` mixin tracks a **hierarchical step index** for each step, stored as the `index` property of each node in the `steps_run` hierarchy, mirroring the nesting of `step` blocks. Each step's input/output state is saved as a JSON file. On re-execution with the same `run_id`, the framework loads the saved state instead of re-running completed steps — saving both time and API costs.
 
 ## Development
 

data/lib/composable_agents/mixins/resumable.rb

@@ -23,6 +23,7 @@ module ComposableAgents
       # @param run_id [String, nil] ID identifying this run to reuse previously executed steps, or nil if there is no resumability needed
       def initialize(*args, run_id: nil, **kwargs)
         super(*args, **kwargs)
+        @steps_run = []
         @run_id = run_id
       end
 
@@ -35,37 +36,59 @@ module ComposableAgents
       def run(**input_artifacts)
         # The artifacts store, JSON serializable
         @artifacts = input_artifacts.dup
-        # List of the levels' next step index, following the hierarchy of recusive step calls.
-        # This is only used if there is a persistent run ID.
-        # For example here are the values of this variable if we have this code:
-        # # @steps_idx == [0]
-        # step(:a) do
-        #   # @steps_idx == [0, 0]
-        #   step(:a1) do
-        #     # @steps_idx == [0, 0, 0]
-        #   end
-        #   # @steps_idx == [0, 1]
-        #   step(:a2) do
-        #     # @steps_idx == [0, 1, 0]
-        #     step(:a21) do
-        #       # @steps_idx == [0, 1, 0, 0]
-        #     end
-        #     # @steps_idx == [0, 1, 1]
-        #     step(:a22) do
-        #       # @steps_idx == [0, 1, 1, 0]
-        #     end
-        #     # @steps_idx == [0, 1, 2]
-        #   end
-        #   # @steps_idx == [0, 2]
-        # end
-        # # @steps_idx == [1]
-        # step(:b) do
-        #   # @steps_idx == [1, 0]
-        # end
-        @steps_idx = [0] unless @run_id.nil?
+        # List of the steps_run hierarchies, one per run. Each run appends its own new list.
+        @steps_run << []
+        @current_step_node = nil
         super
       end
 
+      # Hierarchies of the steps executed during each run of this agent.
+      #
+      # @return [Array<Array<Hash{Symbol => Object}>>>] List of per-run step hierarchies.
+      #   Each element of this array corresponds to a run, and is the ordered list of top-level step nodes of that run.
+      #   Each step node has those properties:
+      #   - step_name [Symbol] The step name.
+      #   - index [Array<Integer>] Position of the step in the hierarchy of recursive step calls.
+      #     It is the succession of indices from the root of the hierarchy to this step node,
+      #     each index being the position of the node among its sibling nodes (children of the same parent).
+      #     For example here are the values of the index property of the step nodes if we have this code:
+      #     # index == [0]
+      #     step(:a) do
+      #       # index == [0, 0]
+      #       step(:a1) do
+      #         # index == [0, 0, 0]
+      #       end
+      #       # index == [0, 1]
+      #       step(:a2) do
+      #         # index == [0, 1, 0]
+      #         step(:a21) do
+      #           # index == [0, 1, 0, 0]
+      #         end
+      #         # index == [0, 1, 1]
+      #         step(:a22) do
+      #           # index == [0, 1, 1, 0]
+      #         end
+      #         # index == [0, 1, 2]
+      #       end
+      #       # index == [0, 2]
+      #     end
+      #     # index == [1]
+      #     step(:b) do
+      #       # index == [1, 0]
+      #     end
+      #   - status [Symbol] The status of the step:
+      #     - `started``: The step has started its execution.
+      #     - `cached``: The step was skipped because of a previous execution.
+      #     - `executed``: The step has completed its execution.
+      #     - `error``: The step has raised an exception during its execution.
+      #   - created_at [Time] Timestamp of the creation of this step node.
+      #   - extra_input_artifacts [Hash] Additional artifacts given as input to this step.
+      #   - agent [Agent, nil] The agent that is invoked in this step, or nil if none.
+      #   - error [String, nil] The message of the exception raised during the step execution.
+      #     This property is only present when the status is `error`.
+      #   - children [Array<Hash>] Sub-steps that are invoked from this step.
+      attr_reader :steps_run
+
       private
 
       # Define a step that can be serialized and resumed.
@@ -105,33 +128,73 @@ module ComposableAgents
       # @param extra_input_artifacts [Hash{Symbol => Object}] Additional input artifacts to merge before the step executes.
       # @yield The code called for this step
       def internal_step(step_name:, agent:, extra_input_artifacts: {})
-        @artifacts.merge!(extra_input_artifacts)
-        if @run_id.nil?
-          yield
-        else
-          # Compute the current step state
-          step_state = current_step_state(agent:)
-          # Read the persisted step state if any
-          step_full_name = "#{@steps_idx.join('-')}-#{step_name}"
-          saved_input_state, saved_output_state = saved_step_states(step_full_name)
-          # If the input exists, it means the step was already executed.
-          # If it is the same state as the current one, skip the step and set the current state to the stored output step state.
-          if step_state == saved_input_state
-            set_current_step_state(saved_output_state, agent:)
-            log_debug "[Step #{step_full_name}] - Already executed - Got #{@artifacts.size} artifacts from persistence: #{@artifacts.keys.join(', ')}"
-          else
-            # Clone state before yielding because it will certainly be modified
-            input_step_state = clone_step_state(step_state)
-            @steps_idx << 0
+        record_step(step_name:, agent:, extra_input_artifacts:) do
+          @artifacts.merge!(extra_input_artifacts)
+          if @run_id.nil?
             yield
-            @steps_idx.pop
-            store_step_states(step_full_name, input: input_step_state, output: current_step_state(agent:))
-            log_debug "[Step #{step_full_name}] - Executed - Stored #{@artifacts.size} artifacts in persistence: #{@artifacts.keys.join(', ')}"
+            @current_step_node[:status] = :executed
+          else
+            # Compute the current step state
+            step_state = current_step_state(agent:)
+            # Read the persisted step state if any
+            step_full_name = "#{@current_step_node[:index].join('-')}-#{step_name}"
+            saved_input_state, saved_output_state = saved_step_states(step_full_name)
+            # If the input exists, it means the step was already executed.
+            # If it is the same state as the current one, skip the step and set the current state to the stored output step state.
+            if step_state == saved_input_state
+              @current_step_node[:status] = :cached
+              set_current_step_state(saved_output_state, agent:)
+              log_debug "[Step #{step_full_name}] - Already executed - Got #{@artifacts.size} artifacts from persistence: #{@artifacts.keys.join(', ')}"
+            else
+              # Clone state before yielding because it will certainly be modified
+              input_step_state = clone_step_state(step_state)
+              yield
+              @current_step_node[:status] = :executed
+              store_step_states(step_full_name, input: input_step_state, output: current_step_state(agent:))
+              log_debug "[Step #{step_full_name}] - Executed - Stored #{@artifacts.size} artifacts in persistence: #{@artifacts.keys.join(', ')}"
+            end
           end
-          @steps_idx[-1] += 1
         end
       end
 
+      # Record a step node in the steps hierarchy, then execute the step's code.
+      # Steps executed while this node is the current one are recorded as its children.
+      #
+      # @param step_name [Symbol] Name of the step, mirroring the one used by the persisted steps.
+      # @param agent [ComposableAgents::Agent, nil] The agent run by this step, or nil for plain steps.
+      # @param extra_input_artifacts [Hash{Symbol => Object}] Input artifacts given to the step.
+      # @yield The code of the step to be executed
+      def record_step(step_name:, agent:, extra_input_artifacts:)
+        @steps_run ||= []
+        parent_node = @current_step_node
+        node = {
+          step_name:,
+          # Compute the index of this step in the hierarchy of recursive step calls:
+          # the indices of the ancestor step nodes, followed by this node's position among its sibling nodes.
+          index: (parent_node ? parent_node[:index] : []) + [(parent_node ? parent_node[:children] : @steps_run.last).size],
+          status: :started,
+          created_at: Time.now,
+          agent:,
+          extra_input_artifacts: extra_input_artifacts.clone,
+          children: []
+        }
+        if parent_node
+          parent_node[:children] << node
+        else
+          @steps_run.last << node
+        end
+        @current_step_node = node
+        begin
+          yield
+        rescue Exception => e # rubocop:disable Lint/RescueException -- Record the error status of any failing step, including Ctrl-C interruptions (Interrupt)
+          node[:status] = :error
+          node[:error] = e.message
+          raise
+        end
+      ensure
+        @current_step_node = parent_node
+      end
+
       # Get the current step state.
       #
       # @param agent [Agent, nil] Agent that is used in this step, or nil if none.

data/lib/composable_agents/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: composable_agents
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.2
 platform: ruby
 authors:
 - Muriel Salvan
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.12'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.12'
 - !ruby/object:Gem::Dependency
   name: cline-rb
   requirement: !ruby/object:Gem::Requirement
@@ -43,28 +43,28 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.10'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.10'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '2.7'
+        version: '2.8'
 email: muriel@x-aeon.com
 executables: []
 extensions: []