composable_agents 1.1.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83d046d554869aa540c97465182338129f2aefbf14f92b20fc0aaf81ef54b632
-  data.tar.gz: 0b86bd8489a1b4b2f66a1ae20c33c543b055c559e07cafddc18924628a58ef01
+  metadata.gz: f0b4d0aa586936486335008d4a263e03e882150495932ca50da5a49f6266b940
+  data.tar.gz: 6dcd208bf7884791fa2ef783312207feee0525e77e1363fbe88068dc260d0e88
 SHA512:
-  metadata.gz: 313bf41f9c1b24ce950ef3071adbf79a1433e4dea0d1b586964ef30854153c4f06e9a44ccbf852c2d798d8bd90e6bf2328f5f35beb799e433b0712250ad076c9
-  data.tar.gz: 94dfd245657963c6566b796d99bd7be1d5609d30c04b68d0ee0a6845f9b1082a33ed6494a3c0b45447120f20ef0f498d064ad3c89e5d7be09f873554de1bb0f4
+  metadata.gz: 57b00fc7d8861359dbc399fd580f86e51f579bc40544b6bceada3cbb18c38d7ca0b895ec26a091295c5004fd43f37639b496898dfd9b8ac5de79326b16fb58ed
+  data.tar.gz: 56b80e997cecf2ceba654865946e8ec915a8bf9553d79738e4760709b2056430400af52fc96efea3043116732dcdc20e38ba3c578b31430c5c284afba10aae33

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+# [v2.0.0](https://github.com/Muriel-Salvan/composable_agents/compare/v1.1.2...v2.0.0) (2026-09-04 12:17:53)
+
+## Global changes
+### Patches
+
+* [[Feature(AiAgents)] Publish realtime LLM usage (cost, tokens) in run info](https://github.com/Muriel-Salvan/composable_agents/commit/e6302ae30ec4a8c54b449c23ebf795f6b6a3e055)
+* [feat(cline): track and publish realtime API usage in run info](https://github.com/Muriel-Salvan/composable_agents/commit/c07eed20e81eda7fd08c32fb28426ca262844aaa)
+* [[Breaking(Resumable)] track steps per run and document resumable run info](https://github.com/Muriel-Salvan/composable_agents/commit/ba839759e24e6a1ca9eb4ee14e552c6b7b8da017)
+* [[Feature(Agent)]: add run tracking and info publishing to agents](https://github.com/Muriel-Salvan/composable_agents/commit/67567699bdfd66d6cf65bd3095e8b08e04ca301e)
+
+## Changes for Agent
+### Features
+
+* [[Feature(Agent)]: add run tracking and info publishing to agents](https://github.com/Muriel-Salvan/composable_agents/commit/67567699bdfd66d6cf65bd3095e8b08e04ca301e)
+
+## Changes for AiAgents
+### Features
+
+* [[Feature(AiAgents)] Publish realtime LLM usage (cost, tokens) in run info](https://github.com/Muriel-Salvan/composable_agents/commit/e6302ae30ec4a8c54b449c23ebf795f6b6a3e055)
+
+## Changes for Resumable
+### Breaking changes
+
+* [[Breaking(Resumable)] track steps per run and document resumable run info](https://github.com/Muriel-Salvan/composable_agents/commit/ba839759e24e6a1ca9eb4ee14e552c6b7b8da017)
+
 # [v1.1.2](https://github.com/Muriel-Salvan/composable_agents/compare/v1.1.1...v1.1.2) (2026-09-03 16:08:18)
 
 ### Patches

data/lib/composable_agents/agent.rb

@@ -7,9 +7,12 @@ module ComposableAgents
 
     # @!group Public API
 
-    # @return [String, nil] The agent name, if any
+    # @return [String, nil] The agent name, if any.
     attr_reader :name
 
+    # @return [Array<RunInfo>] The list of run information of this agent.
+    attr_reader :runs_info
+
     # Constructor
     #
     # @param name [String, nil] Agent name, or nil if none
@@ -20,6 +23,8 @@ module ComposableAgents
     )
       @name = name
       @composable_agents_dir = composable_agents_dir
+      @runs_info = []
+      @current_run_info = nil
     end
 
     # Return the full name of the agent.
@@ -31,23 +36,34 @@ module ComposableAgents
       "#{name || 'Unnamed'}#{" (#{self.class.name.split('::').last})" if self.class != Agent && self.class.name}"
     end
 
-    # @!group Internal
-
     # Execute the agent to generate some output artifacts based on some input artifacts.
     #
-    # @param input_artifacts [Hash{Symbol => Object}] The input artifacts content
+    # @param _input_artifacts [Hash{Symbol => Object}] The input artifacts content
     # @return [Hash{Symbol => Object}] Output artifacts content
-    def run(**input_artifacts)
-      raise NotImplementedError, 'This method should be implemented by an Agent subclass'
+    def run(**_input_artifacts)
+      @current_run_info = RunInfo.new
+      @runs_info << @current_run_info
+      publish_run_info(started_at: Time.now)
+      {}
     end
 
     private
 
+    # @return [RunInfo, nil] The current run info, or nil if no run has started yet
+    attr_reader :current_run_info
+
     # Fields to be logged
     #
     # @return [Array<String>] Fields to log
     def log_fields
       [full_name]
     end
+
+    # Publish run information for the current run
+    #
+    # @param kwargs [Hash{Symbol => Object}] Set of properties to publish
+    def publish_run_info(**kwargs)
+      current_run_info.publish(**kwargs)
+    end
   end
 end

data/lib/composable_agents/ai_agents/agent.rb

@@ -5,6 +5,20 @@ module ComposableAgents
   # All agents from this module work with the awesome ai-agents Rubygem
   module AiAgents
     # Agent implementation that uses an ai-agent's AgentRunner.
+    # This agent publishes the following run information:
+    # - usage [Hash] Cumulative usage (cost and tokens) of the LLM calls made during the run.
+    #   This information is published in realtime, as soon as the AgentRunner completes LLM calls.
+    #   Here are the properties it contains:
+    #   - cost [Float] Cumulative monetary cost of all LLM calls of the run.
+    #     This cost is computed by RubyLLM from the model's pricing in its registry: it is best-effort,
+    #     as models with incomplete pricing information can have their cost underestimated.
+    #   - input_tokens [Integer] Cumulative number of input tokens of all LLM calls of the run.
+    #   - output_tokens [Integer] Cumulative number of output tokens of all LLM calls of the run.
+    #   - cache_read_tokens [Integer] Cumulative number of tokens read from cache by all LLM calls of the run.
+    #   - cache_write_tokens [Integer] Cumulative number of tokens written to cache by all LLM calls of the run.
+    #   - context_tokens [Integer, nil] Number of context tokens consumed by the last LLM call of the run.
+    #     This property is not cumulative, as each LLM call contains the full context.
+    #   - context_tokens_limit [Integer, nil] Maximum context window limit of the model used, or nil if unknown.
     class Agent < PromptDrivenAgent
       # @!group Public API
 
@@ -36,6 +50,18 @@ module ComposableAgents
         "#{name || 'Unnamed'} (AiAgent #{@model})"
       end
 
+      # Execute the agent to generate some output artifacts based on some input artifacts.
+      # Also reset the usage statistics accumulated for this run (published realtime in the run info).
+      #
+      # @param user_instructions [Object, nil] Instructions for the user prompt, that will be rendered.
+      #   The kind of instructions that can be given are defined by the Instructions's constructor (see Instructions#initialize).
+      # @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)
+        @llm_call_responses = []
+        super
+      end
+
       # @!group Internal
 
       # Export the agent state for persistence
@@ -73,9 +99,65 @@ module ComposableAgents
               ] + agent_tools
             )
           ] + @handoff_agents
+        ).on_llm_call_complete { |_agent_name, _model, response| track_llm_usage(response) }
+      end
+
+      # Track usage (cost and tokens) of an LLM call, and publish it realtime in the run info.
+      # The usage of all LLM calls of the run is summed to give the run's cumulative usage.
+      #
+      # @param response [RubyLLM::Message] The response of the LLM call
+      def track_llm_usage(response)
+        # Some responses have no usage metrics (eg. RubyLLM::Tool::Halt responses, or responses without token data)
+        return unless response.respond_to?(:input_tokens) && response.tokens
+
+        @llm_call_responses << response
+        usages = @llm_call_responses
+        last_response = usages.last
+        publish_run_info(
+          usage: {
+            cost: usages.sum { |run_usage| llm_call_cost(run_usage) },
+            input_tokens: usages.sum { |run_usage| run_usage.input_tokens || 0 },
+            output_tokens: usages.sum { |run_usage| run_usage.output_tokens || 0 },
+            cache_read_tokens: usages.sum { |run_usage| run_usage.cached_tokens || 0 },
+            cache_write_tokens: usages.sum { |run_usage| run_usage.cache_creation_tokens || 0 },
+            # Context tokens are not summed, as each LLM call contains the full context: keep the last call's value.
+            context_tokens: llm_call_context_tokens(last_response),
+            context_tokens_limit: llm_call_context_tokens_limit(last_response)
+          }
         )
       end
 
+      # Compute the monetary cost of a single LLM call.
+      # The cost is computed by RubyLLM from the model's pricing in its registry.
+      # Best-effort: components with unknown pricing are not counted (their value is nil).
+      #
+      # @param response [RubyLLM::Message] The response of the LLM call
+      # @return [Float] The monetary cost of the LLM call
+      def llm_call_cost(response)
+        return 0.0 unless response.respond_to?(:cost)
+
+        cost = response.cost
+        %i[input output cache_read cache_write thinking].sum(0.0) { |component| cost.public_send(component) || 0.0 }
+      end
+
+      # Compute the number of context tokens consumed by a single LLM call.
+      # Each LLM call contains the full context of the conversation, plus the tokens generated in its response.
+      #
+      # @param response [RubyLLM::Message] The response of the LLM call
+      # @return [Integer] Number of context tokens consumed by the LLM call
+      def llm_call_context_tokens(response)
+        tokens = response.tokens
+        %i[input output cached cache_creation thinking].sum { |component| tokens.public_send(component) || 0 }
+      end
+
+      # Get the context window limit of the model used by a single LLM call.
+      #
+      # @param response [RubyLLM::Message] The response of the LLM call
+      # @return [Integer, nil] Maximum context window limit of the model, or nil if unknown
+      def llm_call_context_tokens_limit(response)
+        response.model_info&.context_window
+      end
+
       # Process a user prompt.
       #
       # @param user_prompt [String] The rendered user prompt

data/lib/composable_agents/cline/agent.rb

@@ -8,6 +8,18 @@ module ComposableAgents
     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.
+    #   This information is published in realtime, as soon as the Cline CLI reports API requests.
+    #   Here are the properties it contains:
+    #   - cost [Float] Cumulative monetary cost of all API requests of the run.
+    #   - input_tokens [Integer] Cumulative number of input tokens of all API requests of the run.
+    #   - output_tokens [Integer] Cumulative number of output tokens of all API requests of the run.
+    #   - cache_read_tokens [Integer] Cumulative number of tokens read from cache by all API requests of the run.
+    #   - cache_write_tokens [Integer] Cumulative number of tokens written to cache by all API requests of the run.
+    #   - context_tokens [Integer, nil] Number of context tokens consumed by the last API request of the run.
+    #     This property is not cumulative, as each API request contains the full context.
+    #   - context_tokens_limit [Integer, nil] Maximum context window limit of the model used, or nil if unknown.
     class Agent < PromptDrivenAgent
       # @!group Public API
 
@@ -57,6 +69,18 @@ module ComposableAgents
         "#{name || 'Unnamed'} (Cline #{@provider}/#{@model})"
       end
 
+      # Execute the agent to generate some output artifacts based on some input artifacts.
+      # Also reset the usage statistics accumulated for this run (published realtime in the run info).
+      #
+      # @param user_instructions [Object, nil] Instructions for the user prompt, that will be rendered.
+      #   The kind of instructions that can be given are defined by the Instructions's constructor (see Instructions#initialize).
+      # @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)
+        @usage_by_ts = {}
+        super
+      end
+
       # @!group Internal
 
       # Export the agent state for persistence
@@ -112,6 +136,25 @@ module ComposableAgents
                 parse_output_artifacts(content.text) if content.type == 'text' && content.text
               end
             end
+            # Track usage (cost and tokens) of API requests, and publish it realtime in the run info.
+            # Messages are keyed by their timestamp, as the same message can be updated (last version wins),
+            #   and the usage of all API requests of the session is summed to give the run's cumulative usage.
+            next unless (usage = message.usage)
+
+            @usage_by_ts[message.ts] = usage
+            usages = @usage_by_ts.values
+            publish_run_info(
+              usage: {
+                cost: usages.sum { |run_usage| run_usage.cost || 0.0 },
+                input_tokens: usages.sum { |run_usage| run_usage.input_tokens || 0 },
+                output_tokens: usages.sum { |run_usage| run_usage.output_tokens || 0 },
+                cache_read_tokens: usages.sum { |run_usage| run_usage.cache_read_tokens || 0 },
+                cache_write_tokens: usages.sum { |run_usage| run_usage.cache_write_tokens || 0 },
+                # Context tokens are not summed, as each API request contains the full context: keep the last request's value.
+                context_tokens: usages.last&.context_tokens,
+                context_tokens_limit: usages.last&.context_tokens_limit
+              }
+            )
           end,
           **@cli_options
         )

data/lib/composable_agents/mixins/resumable.rb

@@ -15,6 +15,50 @@ module ComposableAgents
     # This mixin uses the following methods from the agent:
     # - `#export_state -> Object` Optional method returning the current JSON-serializable state of the agent.
     # - `#import_state(state)` Optional method that sets the agent state from a JSON-serializable object.
+    #
+    # This mixin publishes the following run information:
+    # - steps [Array<Hash>>] Hierarchy of the steps executed during the 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.
     module Resumable
       # @!group Public API
 
@@ -23,7 +67,6 @@ 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
 
@@ -36,59 +79,11 @@ module ComposableAgents
       def run(**input_artifacts)
         # The artifacts store, JSON serializable
         @artifacts = input_artifacts.dup
-        # List of the steps_run hierarchies, one per run. Each run appends its own new list.
-        @steps_run << []
+        @current_run_steps = []
         @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.
@@ -165,13 +160,13 @@ module ComposableAgents
       # @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 ||= []
+        publish_run_info(steps: @current_run_steps) unless current_run_info.respond_to?(:steps)
         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],
+          index: (parent_node ? parent_node[:index] : []) + [(parent_node ? parent_node[:children] : @current_run_steps).size],
           status: :started,
           created_at: Time.now,
           agent:,
@@ -181,7 +176,7 @@ module ComposableAgents
         if parent_node
           parent_node[:children] << node
         else
-          @steps_run.last << node
+          @current_run_steps << node
         end
         @current_step_node = node
         begin

data/lib/composable_agents/prompt_driven_agent.rb

@@ -68,6 +68,7 @@ module ComposableAgents
     # @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)
+      super
       @input_artifacts = input_artifacts
       @output_artifacts = {}
       @output_artifacts_errors = {}

data/lib/composable_agents/ruby_agent.rb

@@ -22,6 +22,7 @@ module ComposableAgents
     # @param input_artifacts [Hash{Symbol => Object}] The input artifacts content, per artifact name
     # @return [Hash{Symbol => Object}] The output artifacts returned by the Proc
     def run(**input_artifacts)
+      super
       @processor.call(input_artifacts)
     end
   end

data/lib/composable_agents/run_info.rb

@@ -0,0 +1,19 @@
+module ComposableAgents
+  # Store runtime information about a run
+  class RunInfo
+    # Constructor
+    def initialize
+      @properties = {}
+    end
+
+    # Publish properties
+    #
+    # @param kwargs [Hash{Symbol => Object}] Set of properties to publish
+    def publish(**kwargs)
+      kwargs.each do |name, value|
+        @properties[name] = value
+        singleton_class.define_method(name) { @properties.fetch(name) } unless singleton_class.respond_to?(name)
+      end
+    end
+  end
+end

data/lib/composable_agents/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: composable_agents
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 2.0.0
 platform: ruby
 authors:
 - Muriel Salvan
@@ -90,6 +90,7 @@ files:
 - lib/composable_agents/prompt_rendering_strategy/markdown.rb
 - lib/composable_agents/prompt_rendering_strategy/markdown_heavy.rb
 - lib/composable_agents/ruby_agent.rb
+- lib/composable_agents/run_info.rb
 - lib/composable_agents/utils/markdown.rb
 - lib/composable_agents/version.rb
 homepage: https://github.com/Muriel-Salvan/composable_agents