composable_agents 2.0.0 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0b4d0aa586936486335008d4a263e03e882150495932ca50da5a49f6266b940
-  data.tar.gz: 6dcd208bf7884791fa2ef783312207feee0525e77e1363fbe88068dc260d0e88
+  metadata.gz: af07644d98f8997653ead8dc4b2707fe3ff6338480373cbc6fa5c5cc9aa5d82a
+  data.tar.gz: 2824ad225970ce7f3af6ff6e3d64d4a4200638af65bda0263e592466e7793e8d
 SHA512:
-  metadata.gz: 57b00fc7d8861359dbc399fd580f86e51f579bc40544b6bceada3cbb18c38d7ca0b895ec26a091295c5004fd43f37639b496898dfd9b8ac5de79326b16fb58ed
-  data.tar.gz: 56b80e997cecf2ceba654865946e8ec915a8bf9553d79738e4760709b2056430400af52fc96efea3043116732dcdc20e38ba3c578b31430c5c284afba10aae33
+  metadata.gz: 154a31e282dccb4b9c2f02a45b4ec2322b6dd269e63f9e21d0f7f9d239c5a087307d62c905a23ed5ca7981cd6fce8bf4bd4005ba80165f251d0c5b5d36d57440
+  data.tar.gz: 4f0d0b0ad45ab9a72ab206fd41d6d420dc167f0b3a66b3fd485f76ebece746d47eff3a9d17e7d2d66570369cda52eb1036eb44b1a59459b8626c063cf62eaa69

data/CHANGELOG.md

@@ -1,3 +1,16 @@
+# [v2.1.0](https://github.com/Muriel-Salvan/composable_agents/compare/v2.0.0...v2.1.0) (2026-09-06 16:41:14)
+
+## Global changes
+### Patches
+
+* [fix: return nil on JSON parse failure to skip artifact save](https://github.com/Muriel-Salvan/composable_agents/commit/2f70822a9142d97aa9d5fa9424a8f9c97f98208e)
+* [[Feature(Agent)] Added configurable logger for all agents.](https://github.com/Muriel-Salvan/composable_agents/commit/2979d6de1ea73bb259147f3778d6a51481c79f22)
+
+## Changes for Agent
+### Features
+
+* [[Feature(Agent)] Added configurable logger for all agents.](https://github.com/Muriel-Salvan/composable_agents/commit/2979d6de1ea73bb259147f3778d6a51481c79f22)
+
 # [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

data/README.md

@@ -49,7 +49,7 @@ Whether you're building a code review assistant, a document summarizer, or a mul
     - [`ComposableAgents::Cline::Agent < PromptDrivenAgent`](#composableagentsclineagent--promptdrivenagent)
     - [`ComposableAgents::Cline::MissingSkillError < RuntimeError`](#composableagentsclinemissingskillerror--runtimeerror)
   - [Mixins](#mixins)
-    - [`ComposableAgents::Mixins::Logger`](#composableagentsmixinslogger)
+    - [`ComposableAgents::Logger < ::Logger`](#composableagentslogger--logger)
     - [`ComposableAgents::Mixins::Resumable`](#composableagentsmixinsresumable)
     - [`ComposableAgents::Mixins::UserInteraction`](#composableagentsmixinsuserinteraction)
     - [`ComposableAgents::Mixins::ArtifactContract`](#composableagentsmixinsartifactcontract)
@@ -365,18 +365,16 @@ The project is a Ruby library (not a CLI) — users install the gem and use its
 
 Mixins are `prepend`-ed into an agent class to add specific capabilities.
 
-#### `ComposableAgents::Mixins::Logger`
+#### `ComposableAgents::Logger < ::Logger`
 
-- **Description:** Provides debug and info logging to agents. Debug mode is enabled by setting `COMPOSABLE_AGENTS_DEBUG=1` in the environment.
-- **Public methods (class-level):**
-  - `self.debug?` — Returns `true` if debug mode is enabled (`ENV['COMPOSABLE_AGENTS_DEBUG'] == '1'`).
+- **Description:** Standard Ruby `::Logger`-based logger for agents. Debug logging is enabled by setting `COMPOSABLE_AGENTS_DEBUG=1` in the environment (which sets the logger level to `DEBUG`), and log fields (like the agent full name) can be prefixed to messages via `#tagged`.
 - **Usage example:**
   ```ruby
   # Enable debug logs
   ENV['COMPOSABLE_AGENTS_DEBUG'] = '1'
-  puts ComposableAgents::Mixins::Logger.debug?  # => true
+  puts ComposableAgents::Logger.instance.level == Logger::DEBUG  # => true
   ```
-- **Full documentation:** [Mixins::Logger on RubyDoc](https://www.rubydoc.info/gems/composable_agents/ComposableAgents/Mixins/Logger) | [logger.rb on GitHub](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/logger.rb)
+- **Full documentation:** ComposableAgents::Logger on RubyDoc | [logger.rb on GitHub](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/logger.rb)
 
 #### `ComposableAgents::Mixins::Resumable`
 
@@ -479,7 +477,7 @@ Mixins are `prepend`-ed into an agent class to add specific capabilities.
   - [`Mixins::Resumable`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/resumable.rb) — Resumable workflow mixin
   - [`Mixins::ArtifactContract`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/artifact_contract.rb) — Artifact validation mixin
   - [`Mixins::UserInteraction`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/user_interaction.rb) — User question-asking mixin
-  - [`Mixins::Logger`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/mixins/logger.rb) — Debug logging mixin
+  - [`Logger`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/logger.rb) — Standard logger class
   - [`PromptRenderingStrategy::Markdown`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/prompt_rendering_strategy/markdown.rb) — Markdown prompt strategy
   - [`PromptRenderingStrategy::MarkdownHeavy`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/prompt_rendering_strategy/markdown_heavy.rb) — Heavy Markdown prompt strategy
   - [`Utils::Markdown`](https://github.com/Muriel-Salvan/composable_agents/blob/main/lib/composable_agents/utils/markdown.rb) — Markdown header alignment utilities
@@ -524,7 +522,7 @@ classDiagram
 
 The framework provides a clean **4-class hierarchy**:
 
-- **`Agent`** — Abstract base class. Defines the `run(**input_artifacts)` contract and includes the [`Mixins::Logger`](lib/composable_agents/mixins/logger.rb) for debug/info logging.
+- **`Agent`** — Abstract base class. Defines the `run(**input_artifacts)` contract and includes the [`Logger`](lib/composable_agents/logger.rb) for debug/info logging.
 - **`RubyAgent`** — Wraps any Ruby `Proc` as an agent. No LLM involved: call `proc.call(input_artifacts)` and return a hash. Ideal for deterministic logic.
 - **`PromptDrivenAgent`** — Base for LLM-powered agents. Holds a **role**, **objective**, **system_instructions**, and **constraints**. Renders them via a pluggable **prompt rendering strategy** and records every prompt/response in a `conversation` array.
 - **`AiAgents::Agent` / `Cline::Agent`** — Concrete LLM backends: one wraps the [`ai-agents`](https://github.com/nicbarker/ai-agents) gem, the other wraps [`cline-rb`](https://github.com/Muriel-Salvan/cline-rb). Both implement `#prompt(user_prompt)` to send the rendered prompt to the LLM.
@@ -584,7 +582,6 @@ Mixins are **prepended** (using `prepend`) or **included** (using `include`) to
 - **[`Mixins::ArtifactContract`](lib/composable_agents/mixins/artifact_contract.rb)** — Wraps `#run` to validate inputs before and outputs after execution against declared contracts. Raises `MissingInputArtifactError`, `MissingOutputArtifactError`, or `ArtifactTypeError` on violations.
 - **[`Mixins::Resumable`](lib/composable_agents/mixins/resumable.rb)** — Overrides `#run` with a **step-based execution model**. Each `step` block is persisted to `.composable_agents/runs/{run_id}/` as JSON. On re-run, completed steps are skipped — only new steps execute. Supports nested steps and agent state serialization via `export_state`/`import_state`.
 - **[`Mixins::UserInteraction`](lib/composable_agents/mixins/user_interaction.rb)** — Adds an `#ask(question)` method. By default prompts the terminal; override `#answer_to` for custom behavior.
-- **[`Mixins::Logger`](lib/composable_agents/mixins/logger.rb)** — Provides `log_debug`/`log_info` methods. Debug output is toggled via the `COMPOSABLE_AGENTS_DEBUG=1` environment variable.
 
 ### Instruction system 📋
 

data/lib/composable_agents/agent.rb

@@ -3,8 +3,6 @@ module ComposableAgents
   # Agents may internally use LLMs, tools, or other agents.
   # Agents are stateless: they take input artifacts and return output artifacts.
   class Agent
-    include Mixins::Logger
-
     # @!group Public API
 
     # @return [String, nil] The agent name, if any.
@@ -17,12 +15,18 @@ module ComposableAgents
     #
     # @param name [String, nil] Agent name, or nil if none
     # @param composable_agents_dir [String] Base directory where composable agents can store data
+    # @param logger [::Logger] Logger to be used by this agent. Any Ruby-like logger is accepted.
+    #   Defaults to ComposableAgents::Logger's singleton instance.
+    #   This agent's log fields (see #log_fields) are prefixed to logged messages when the logger supports it
+    #     (see ComposableAgents::Logger#tagged), and are left as-is otherwise.
     def initialize(
       name: nil,
-      composable_agents_dir: '.composable_agents'
+      composable_agents_dir: '.composable_agents',
+      logger: ComposableAgents::Logger.instance
     )
       @name = name
       @composable_agents_dir = composable_agents_dir
+      @provided_logger = logger
       @runs_info = []
       @current_run_info = nil
     end
@@ -52,6 +56,15 @@ module ComposableAgents
     # @return [RunInfo, nil] The current run info, or nil if no run has started yet
     attr_reader :current_run_info
 
+    # Get the logger to be used by this agent, with this agent's log fields (see #log_fields) prefixed to messages.
+    # If the provided logger does not support fields tagging, it is used as-is (fields are ignored).
+    # Memoized.
+    #
+    # @return [::Logger] The logger to be used by this agent
+    def logger
+      @logger ||= @provided_logger.respond_to?(:tagged) ? @provided_logger.tagged(*log_fields) : @provided_logger
+    end
+
     # Fields to be logged
     #
     # @return [Array<String>] Fields to log

data/lib/composable_agents/ai_agents/agent.rb

@@ -94,8 +94,8 @@ module ComposableAgents
               params: @params,
               instructions: @system_prompt,
               tools: [
-                Tools::CreateArtifactTool.new(self),
-                Tools::GetArtifactTool.new(@input_artifacts)
+                Tools::CreateArtifactTool.new(self, logger:),
+                Tools::GetArtifactTool.new(@input_artifacts, logger:)
               ] + agent_tools
             )
           ] + @handoff_agents

data/lib/composable_agents/ai_agents/tools/ask_user_tool.rb

@@ -1,13 +1,10 @@
 module ComposableAgents
   module AiAgents
-    # Collection of tools that can be used with ai-agents' agents
     module Tools
       # Tool that is used to ask the user for some input
-      class AskUserTool < Agents::Tool
+      class AskUserTool < BaseTool
         # @!group Internal
 
-        include Mixins::Logger
-
         description <<~EO_DESCRIPTION
           Ask the user a question and wait for their response.
           If you need information from the user, call this tool instead of asking directly.
@@ -18,8 +15,10 @@ module ComposableAgents
         # Constructor
         #
         # @param agent [Agent] The agent that is using this tool
-        def initialize(agent)
-          super()
+        # @param logger [::Logger] Logger to be used by this tool. Any Ruby-like logger is accepted.
+        #   Defaults to ComposableAgents::Logger's singleton instance.
+        def initialize(agent, logger: ComposableAgents::Logger.instance)
+          super(logger:)
           @agent = agent
         end
 

data/lib/composable_agents/ai_agents/tools/base_tool.rb

@@ -0,0 +1,22 @@
+module ComposableAgents
+  module AiAgents
+    # Collection of tools that can be used with ai-agents' agents
+    module Tools
+      # Base class for all tools used by agents.
+      # It provides a logger to all tools, that can be set to any Ruby-like logger
+      #   and defaults to ComposableAgents::Logger's singleton instance.
+      class BaseTool < Agents::Tool
+        # @!group Internal
+
+        # Constructor
+        #
+        # @param logger [::Logger] Logger to be used by this tool. Any Ruby-like logger is accepted.
+        #   Defaults to ComposableAgents::Logger's singleton instance.
+        def initialize(logger: ComposableAgents::Logger.instance)
+          super()
+          @logger = logger
+        end
+      end
+    end
+  end
+end

data/lib/composable_agents/ai_agents/tools/create_artifact_tool.rb

@@ -2,11 +2,9 @@ module ComposableAgents
   module AiAgents
     module Tools
       # Tool that is used to create a new artifact's content
-      class CreateArtifactTool < Agents::Tool
+      class CreateArtifactTool < BaseTool
         # @!group Internal
 
-        include Mixins::Logger
-
         description <<~EO_DESCRIPTION
           Create an output artifact.
           Only create artifacts when the user is asking you to create an artifact named `{name}`.
@@ -18,8 +16,10 @@ module ComposableAgents
         # Constructor
         #
         # @param agent [PromptDrivenAgent] The agent that will receive output artifacts
-        def initialize(agent)
-          super()
+        # @param logger [::Logger] Logger to be used by this tool. Any Ruby-like logger is accepted.
+        #   Defaults to ComposableAgents::Logger's singleton instance.
+        def initialize(agent, logger: ComposableAgents::Logger.instance)
+          super(logger:)
           @agent = agent
         end
 

data/lib/composable_agents/ai_agents/tools/get_artifact_tool.rb

@@ -2,19 +2,19 @@ module ComposableAgents
   module AiAgents
     module Tools
       # Tool that is used to read an artifact's content
-      class GetArtifactTool < Agents::Tool
+      class GetArtifactTool < BaseTool
         # @!group Internal
 
-        include Mixins::Logger
-
         description 'Get an input artifact'
         param :name, type: 'string', desc: 'Artifact name'
 
         # Constructor
         #
         # @param artifacts [Hash{Symbol => Object}>] The artifacts store
-        def initialize(artifacts)
-          super()
+        # @param logger [::Logger] Logger to be used by this tool. Any Ruby-like logger is accepted.
+        #   Defaults to ComposableAgents::Logger's singleton instance.
+        def initialize(artifacts, logger: ComposableAgents::Logger.instance)
+          super(logger:)
           @artifacts = artifacts
         end
 
@@ -27,7 +27,7 @@ module ComposableAgents
         def perform(_tool_context, name:)
           name_sym = name.to_sym
           if @artifacts.key?(name_sym)
-            log_debug "Artifact `#{name}` read successfully."
+            @logger.debug "Artifact `#{name}` read successfully."
             @artifacts[name_sym].to_s.strip
           else
             "[ERROR] No artifact named #{name}, don't call this tool with the name #{name} anymore."

data/lib/composable_agents/cline/agent.rb

@@ -209,7 +209,7 @@ module ComposableAgents
           # Setup the temporary Cline global config dir
           agent_tmp_dir = "#{@composable_agents_dir}/tmp/#{Time.now.utc.strftime('%F-%H-%M-%S')}#{"-#{name.gsub(/[^\w.]/, '_')}" if name}"
           ::Cline.configure do |config|
-            config.debug = Mixins::Logger.debug?
+            config.debug = logger_debug?
             config.temp_dir_root = "#{agent_tmp_dir}/cline-rb"
           end
           cline_config = ::Cline::Config.open("#{agent_tmp_dir}/cline_config", create: true)
@@ -219,7 +219,7 @@ module ComposableAgents
               new_skill = cline_config.skills.new(skill_name)
               new_skill.files.replace(::Cline::Config.global.skills[skill_name].files)
               new_skill.enable
-              log_debug "[Cline] - Enable global skill #{skill_name}"
+              logger.debug "[Cline] - Enable global skill #{skill_name}"
               new_skill.save
             end
           end
@@ -229,10 +229,10 @@ module ComposableAgents
             next if skill.enabled? == selected_skill
 
             if selected_skill
-              log_debug "[Cline] - Enable project skill #{skill_name}"
+              logger.debug "[Cline] - Enable project skill #{skill_name}"
               skill.enable
             else
-              log_debug "[Cline] - Disable project skill #{skill_name}"
+              logger.debug "[Cline] - Disable project skill #{skill_name}"
               skill.disable
             end
             skill.save
@@ -261,10 +261,17 @@ module ComposableAgents
           global_settings.auto_update_enabled = false
           @configure_global&.call(global_settings)
           global_settings.save
-          cline_config.cli(stdout_echo: Mixins::Logger.debug?, verbose: Mixins::Logger.debug?)
+          cline_config.cli(stdout_echo: logger_debug?, verbose: logger_debug?)
         end
       end
 
+      # Check if the agent's logger is set to a debug level.
+      #
+      # @return [Boolean] True if the logger level is DEBUG or lower
+      def logger_debug?
+        @provided_logger.respond_to?(:level) && @provided_logger.level <= ::Logger::DEBUG
+      end
+
       # Find a skill among the current Cline environment (global and project) and recursively finds all its dependencies.
       #
       # @param skill [String] The skill name we are looking for

data/lib/composable_agents/logger/tagged.rb

@@ -0,0 +1,110 @@
+require 'logger'
+
+module ComposableAgents
+  # Proxy around any Ruby-like logger that prefixes fields to the logged messages.
+  # This is a standard ::Logger that inherits all the severity methods (debug, info, warn, error, fatal, unknown),
+  #   but overrides the add/log methods to delegate the actual logging to the wrapped logger,
+  #   with the given fields prefixed to the message.
+  # Messages can be given as a String or a Proc returning the message (for lazy evaluation).
+  class Logger::Tagged < ::Logger
+    # Mapping of severity values to the corresponding severity methods on the wrapped logger
+    SEVERITY_METHODS = {
+      ::Logger::DEBUG => :debug,
+      ::Logger::INFO => :info,
+      ::Logger::WARN => :warn,
+      ::Logger::ERROR => :error,
+      ::Logger::FATAL => :fatal,
+      ::Logger::UNKNOWN => :unknown
+    }.freeze
+
+    # @!group Public API
+
+    # Constructor
+    #
+    # @param logger [Object] Any Ruby-like logger responding to the standard severity methods
+    # @param fields [Array<String>] Fields to be prefixed to each logged message
+    def initialize(logger, fields)
+      @logger = logger
+      @fields = fields
+      # This proxy does not log on its own: the wrapped logger does. Its level is kept in sync so that
+      #   the inherited level predicates (debug?, info?...) reflect the wrapped logger's level.
+      super(nil, level: logger.respond_to?(:level) ? logger.level : ::Logger::DEBUG)
+    end
+
+    # Log a message with the given severity, delegating to the wrapped logger with the fields prefixed.
+    # This is the implementation used by all severity methods, that all call #add in ::Logger.
+    #
+    # @param severity [Integer, nil] Severity of the message
+    # @param message [String, #call => String, nil] Message string, Proc returning the message for lazy evaluation,
+    #   or nil if the message is given by the progname or a block
+    # @param progname [String, nil] Program name to be logged if the message is nil
+    # @yield The optional code returning the message to log
+    # @yieldreturn [String] The message to log
+    # @return [Boolean] True, as ::Logger#add does
+    def add(severity, message = nil, progname = nil, &)
+      log_message(severity, message, progname, &)
+    end
+
+    # Log a message with the given severity.
+    # Defined because ::Logger defines #log as an alias of #add, and aliases are bound at definition time:
+    #   without redefining it here, #log would not use this class' #add override.
+    #
+    # @param severity [Integer, nil] Severity of the message
+    # @param message [String, #call => String, nil] Message string, Proc returning the message for lazy evaluation,
+    #   or nil if the message is given by the progname or a block
+    # @param progname [String, nil] Program name to be logged if the message is nil
+    # @yield The optional code returning the message to log
+    # @yieldreturn [String] The message to log
+    # @return [Boolean] True, as ::Logger#add does
+    def log(severity, message = nil, progname = nil, &)
+      add(severity, message, progname, &)
+    end
+
+    private
+
+    # Delegate the message to the wrapped logger, with the fields prefixed.
+    # The message is evaluated lazily (only when the wrapped logger's severity level allows it),
+    #   by passing a block to the wrapped logger's severity method.
+    #
+    # @param severity [Integer, nil] Severity of the message
+    # @param message [String, #call => String, nil] Message string, Proc returning the message for lazy evaluation,
+    #   or nil if the message is given by the progname or a block
+    # @param progname [String, nil] Program name to be logged if the message is nil
+    # @yield The optional code returning the message to log
+    # @yieldreturn [String] The message to log
+    def log_message(severity, message, progname, &)
+      @logger.public_send(SEVERITY_METHODS.fetch(severity || ::Logger::UNKNOWN, :unknown)) do
+        resolved = resolve_message(message, progname, &)
+        prefix = fields_prefix
+        prefix.empty? ? resolved.to_s : "#{prefix} - #{resolved}"
+      end
+    end
+
+    # Get the fields to be prefixed to logged messages, formatted
+    #
+    # @return [String] The formatted fields prefix
+    def fields_prefix
+      @fields.map { |field| "[#{field}]" }.join(' ')
+    end
+
+    # Resolve the message to be logged.
+    # The block has priority over the message and progname parameters, and Procs are called to get their result.
+    #
+    # @param message [String, #call => String, nil] Message string or Proc returning the message
+    # @param progname [String, nil] Program name to be logged if the message is nil
+    # @yield The optional code returning the message to log
+    # @yieldreturn [String] The message to log
+    # @return [String] The message to be logged
+    def resolve_message(message, progname, &)
+      resolved =
+        if block_given?
+          yield
+        elsif message.nil?
+          progname
+        else
+          message
+        end
+      resolved.respond_to?(:call) ? resolved.call : resolved
+    end
+  end
+end

data/lib/composable_agents/logger.rb

@@ -0,0 +1,48 @@
+require 'logger'
+
+module ComposableAgents
+  # Logger to be used by agents.
+  # This is a standard Ruby Logger (inheriting from ::Logger) that formats messages with a UTC timestamp and severity.
+  # It also supports prefixing fields to messages (like the agent's full name) using the #tagged method,
+  #   which returns a proxy compatible with any Ruby-like logger: fields are then prepended to the logged messages
+  #   themselves, and silently ignored by loggers not supporting them.
+  class Logger < ::Logger
+    # @!group Public API
+
+    class << self
+      # Get the default singleton logger instance
+      #
+      # @return [Logger] The default logger instance
+      def instance
+        @instance ||= new
+      end
+    end
+
+    # Constructor.
+    # Unless overridden by the caller, the default level follows the COMPOSABLE_AGENTS_DEBUG environment variable
+    #   (DEBUG when it is set to 1, INFO otherwise), and the default formatter outputs messages as
+    #   `[UTC timestamp] [SEVERITY] message`.
+    #
+    # @param logdev [IO, String, #write, nil] Log device to be used, defaulting to standard output
+    # @param args [Array<Object>] Positional arguments to be given to ::Logger (shifting parameters...)
+    # @param kwargs [Hash{Symbol => Object}] Optional parameters to be given to ::Logger (level, formatter...)
+    def initialize(logdev = $stdout, *args, **kwargs)
+      super
+      self.level = ENV['COMPOSABLE_AGENTS_DEBUG'] == '1' ? DEBUG : INFO unless kwargs.key?(:level)
+      return if kwargs.key?(:formatter)
+
+      self.formatter = proc do |severity, _datetime, _progname, message|
+        "[#{Time.now.utc.strftime('%F %T')}] [#{severity}] #{message}\n"
+      end
+    end
+
+    # Get a logger proxy that prefixes the given fields to logged messages.
+    # The returned proxy is compatible with any Ruby-like logger.
+    #
+    # @param fields [Array<String>] Fields to be prefixed to each logged message
+    # @return [Tagged] The fields-prefixing logger proxy
+    def tagged(*fields)
+      Tagged.new(self, fields)
+    end
+  end
+end

data/lib/composable_agents/mixins/ai_agent_user_interaction.rb

@@ -16,7 +16,7 @@ module ComposableAgents
       #
       # @return [Array<Agents::Tool>] List of tools
       def agent_tools
-        super + [AiAgents::Tools::AskUserTool.new(self)]
+        super + [AiAgents::Tools::AskUserTool.new(self, logger:)]
       end
     end
   end

data/lib/composable_agents/mixins/resumable.rb

@@ -2,6 +2,7 @@ require 'json'
 require 'fileutils'
 
 module ComposableAgents
+  # Collection of useful mixins that add functionality to agents prepending them.
   module Mixins
     # Mixin adding resumable step capabilities to agents.
     # An agent prepending this mixin can use the following:
@@ -139,14 +140,14 @@ module ComposableAgents
             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(', ')}"
+              logger.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(', ')}"
+              logger.debug "[Step #{step_full_name}] - Executed - Stored #{@artifacts.size} artifacts in persistence: #{@artifacts.keys.join(', ')}"
             end
           end
         end

data/lib/composable_agents/prompt_driven_agent.rb

@@ -73,7 +73,7 @@ module ComposableAgents
       @output_artifacts = {}
       @output_artifacts_errors = {}
       @system_prompt = render_system_prompt(render_instructions(@system_instructions))
-      log_debug "System prompt: #{@system_prompt}"
+      logger.debug "System prompt: #{@system_prompt}"
       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.
@@ -148,7 +148,7 @@ module ComposableAgents
     def save_output_artifact(artifact_name, content)
       @output_artifacts[artifact_name] = content
       @output_artifacts_errors.delete(artifact_name)
-      log_debug "[Artifact] - Received output artifact #{artifact_name}"
+      logger.debug "[Artifact] - Received output artifact #{artifact_name}"
     end
 
     # Report an error on an output artifact.
@@ -162,7 +162,7 @@ module ComposableAgents
       @output_artifacts.delete(artifact_name)
       @output_artifacts_errors[artifact_name] = error
       # TODO: Make this as a warning message
-      log_debug "[Artifact] - Should have received content for output artifact `#{artifact_name}` " \
+      logger.debug "[Artifact] - Should have received content for output artifact `#{artifact_name}` " \
         "but the following error occurred: #{error}"
     end
 
@@ -191,10 +191,10 @@ module ComposableAgents
     def converse(instructions, input_artifacts: {}, author: 'Orchestrator')
       rendered_instructions = render_instructions(instructions)
       rendered_user_prompt = render_user_prompt(rendered_instructions, input_artifacts:)
-      log_debug "Rendered User prompt: #{rendered_user_prompt}"
+      logger.debug "Rendered User prompt: #{rendered_user_prompt}"
       track_message(message: rendered_instructions, author:)
       response = prompt(rendered_user_prompt)
-      log_debug "Raw Agent #{full_name} response: #{response}"
+      logger.debug "Raw Agent #{full_name} response: #{response}"
       track_message(message: response, author: "Agent #{full_name}")
     end
 

data/lib/composable_agents/prompt_rendering_strategy/markdown_heavy.rb

@@ -169,7 +169,8 @@ module ComposableAgents
       #   - error [String, nil] An error message related to this missing artifact.
       # @return [Object] The user instructions (see Instructions#initialize)
       def missing_output_user_instructions(missing_output_artifacts)
-        log_debug "[Artifact] - Asking assistant for missing output artifacts `#{missing_output_artifacts.keys.join(', ')}` to be returned in its next answer."
+        logger.debug '[Artifact] - Asking assistant for missing output artifacts ' \
+          "`#{missing_output_artifacts.keys.join(', ')}` to be returned in its next answer."
         <<~EO_PROMPT
           The following output artifacts are missing from your previous responses:
           #{

data/lib/composable_agents/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: composable_agents
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Muriel Salvan
@@ -77,13 +77,15 @@ files:
 - lib/composable_agents/agent.rb
 - lib/composable_agents/ai_agents/agent.rb
 - lib/composable_agents/ai_agents/tools/ask_user_tool.rb
+- 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/cline/agent.rb
 - lib/composable_agents/instructions.rb
+- lib/composable_agents/logger.rb
+- lib/composable_agents/logger/tagged.rb
 - lib/composable_agents/mixins/ai_agent_user_interaction.rb
 - lib/composable_agents/mixins/artifact_contract.rb
-- lib/composable_agents/mixins/logger.rb
 - lib/composable_agents/mixins/resumable.rb
 - lib/composable_agents/mixins/user_interaction.rb
 - lib/composable_agents/prompt_driven_agent.rb

data/lib/composable_agents/mixins/logger.rb

@@ -1,47 +0,0 @@
-module ComposableAgents
-  # Collection of useful mixins that add functionality to agents prepending them.
-  module Mixins
-    # Logging mixin for agents
-    module Logger
-      # @!group Public API
-
-      # Check if debug mode is enabled
-      #
-      # @return [Boolean] True if debug mode is enabled
-      def self.debug?
-        ENV['COMPOSABLE_AGENTS_DEBUG'] == '1'
-      end
-
-      private
-
-      # Log debug message only if debug mode is enabled
-      #
-      # @param message [String, Proc] Message string or Proc returning message for lazy evaluation
-      def log_debug(message)
-        return unless Logger.debug?
-
-        log(message, severity: :debug)
-      end
-
-      # Log info message
-      #
-      # @param message [String, #call => String] Message string or Proc returning message for lazy evaluation
-      def log_info(message)
-        log(message, severity: :info)
-      end
-
-      # Log a message with severity
-      #
-      # @param message [String, #call => String] Message string or Proc returning message for lazy evaluation
-      # @param severity [Symbol] Severity
-      def log(message, severity: :info)
-        fields = [
-          Time.now.utc.strftime('%F %T'),
-          severity.to_s.upcase
-        ]
-        fields.concat(log_fields) if respond_to?(:log_fields, true)
-        puts "#{fields.map { |field| "[#{field}]" }.join(' ')} - #{message.is_a?(String) ? message : message.call}"
-      end
-    end
-  end
-end