composable_agents 3.7.0 → 3.7.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 753d56bfc73e0b268d107ae37338f3efa465fc1fe559813228aa3498e6544d9e
-  data.tar.gz: 21ac2d0a614a3044f392675dd988dce82c4ffcc5cb2c5192ae9a8f32416bab1d
+  metadata.gz: 816f8fd0898371ab594b7572d3154736711898c01d93de8269a7df6dfdeca623
+  data.tar.gz: be371808032d40d5464bd6e1292f6f395732ddb1e1fb0875e5f0736884856106
 SHA512:
-  metadata.gz: 39d7fb3e1d61adb4ed78ca652b1f1aa5fc9b689cea004305de6ba14a56646725762ffb1c72965a69a516c804c5f3231197b474ebdcc4119830f708c9c85135b0
-  data.tar.gz: b2a60316353effb352cd785e54faa5f0b3d07a01f3c46fdf447f0dfdb57dc990f495ed12fddaf70eeb800cccac4b05b71ac14543bf9057c17b32f90a313dd09a
+  metadata.gz: a5ec7f64ec25d84e17ef9a4e97878223fbfe12304442f0622d5f5953e9c3922b8787fea20cfd2fbe57c9c9e21928b6a7bc8aed4c14d8612d0f77abed78a3742b
+  data.tar.gz: e9a2a731c1a3885d00b239ccbf547dc03badc096afd57d52cc917c02b07e85cdd34d530be87cb4c384bee2fbee77867e22e3a338aae23aa1420bc790354b5546

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+# [v3.7.2](https://github.com/Muriel-Salvan/composable_agents/compare/v3.7.1...v3.7.2) (2026-11-12 15:34:25)
+
+## Global changes
+### Patches
+
+* [fix(strategies): expose options through agent accessors](https://github.com/Muriel-Salvan/composable_agents/commit/5a6901d858f6382e63efa49edd4dabf21efd8082)
+
+## Changes for strategies
+### Patches
+
+* [fix(strategies): expose options through agent accessors](https://github.com/Muriel-Salvan/composable_agents/commit/5a6901d858f6382e63efa49edd4dabf21efd8082)
+
+# [v3.7.1](https://github.com/Muriel-Salvan/composable_agents/compare/v3.7.0...v3.7.1) (2026-11-12 13:28:25)
+
+## Global changes
+### Patches
+
+* [fix(MarkdownHeavyFiles): lazy-init MarkdownHeavyFiles artifact dirs](https://github.com/Muriel-Salvan/composable_agents/commit/bb64c69e65a60130e356c70755d0b862586a5351)
+
+## Changes for MarkdownHeavyFiles
+### Patches
+
+* [fix(MarkdownHeavyFiles): lazy-init MarkdownHeavyFiles artifact dirs](https://github.com/Muriel-Salvan/composable_agents/commit/bb64c69e65a60130e356c70755d0b862586a5351)
+
 # [v3.7.0](https://github.com/Muriel-Salvan/composable_agents/compare/v3.6.1...v3.7.0) (2026-11-12 12:08:18)
 
 ## Global changes

data/README.md

@@ -568,7 +568,7 @@ When a proc returns a policy, the agent waits `wait_secs` seconds, applies the `
 ### Additional notes
 
 - **No executables / CLI** — This gem is a library only; there are no scripts in `bin/`.
-- **Prompt rendering strategies** (`PromptRenderingStrategy::Markdown`, `PromptRenderingStrategy::MarkdownHeavy`, and `PromptRenderingStrategy::MarkdownHeavyFiles`) are not part of the public API themselves — they are included automatically by the agent's `strategy:` parameter.
+- **Prompt rendering strategies** (`PromptRenderingStrategy::Markdown`, `PromptRenderingStrategy::MarkdownHeavy`, and `PromptRenderingStrategy::MarkdownHeavyFiles`) are not part of the public API themselves — they are included automatically by the agent's `strategy:` parameter. A strategy never defines `initialize`: when it can be customized, it exposes public accessors on the agent, resolved lazily and set at any time after construction (e.g. `PromptRenderingStrategy::MarkdownHeavyFiles#artifacts_directory=`).
 - **The `AiAgentUserInteraction` mixin** (`ComposableAgents::Mixins::AiAgentUserInteraction`) is an internal bridge that combines `UserInteraction` with `AiAgents::Agent`; it is used by prepending it to an `AiAgents::Agent` subclass.
 - See the [examples/](https://github.com/Muriel-Salvan/composable_agents/tree/main/examples) directory for complete, runnable scripts demonstrating all the above APIs.
 
@@ -679,7 +679,7 @@ Three strategies are included, mixed into the agent at initialization via `singl
 
 - **`PromptRenderingStrategy::Markdown`** — Clean, minimal Markdown. Simple instructions and artifact references.
 - **`PromptRenderingStrategy::MarkdownHeavy`** (default for Cline) — Elaborate prompts with execution checklists, structured artifact definition sections, and **JSON-based output parsing**. Agents format their artifacts as JSON blocks tagged with `output_artifact=NAME`, which the strategy parses back into the output hash. Includes type-aware parsing (`:text`, `:markdown`, `:json`).
-- **`PromptRenderingStrategy::MarkdownHeavyFiles`** — Same heavy Markdown behavior as `MarkdownHeavy`, but artifacts are persisted as files on disk instead of being in-lined or returned as JSON. Input artifacts are written to files that the assistant is asked to open, and output artifacts are expected as files that are read back from disk. Accepts an `artifacts_directory` constructor parameter (defaults to `#{composable_agents_dir}/artifacts`).
+- **`PromptRenderingStrategy::MarkdownHeavyFiles`** — Same heavy Markdown behavior as `MarkdownHeavy`, but artifacts are persisted as files on disk instead of being in-lined or returned as JSON. Input artifacts are written to files that the assistant is asked to open, and output artifacts are expected as files that are read back from disk. It exposes a public `#artifacts_directory` accessor (defaulting to `#{composable_agents_dir}/artifacts`) that can be set on the agent at any time; its artifacts directories are resolved lazily and created on first use. Example: `agent.artifacts_directory = File.join(composable_agents_dir, 'my_artifacts')`.
 
 ### LLM backends: ai-agents vs cline-rb 🎯
 

data/lib/composable_agents/agent.rb

@@ -56,6 +56,10 @@ module ComposableAgents
     # @return [RunInfo, nil] The current run info, or nil if no run has started yet
     attr_reader :current_run_info
 
+    # @return [String] Base directory where this agent stores its data (runs, artifacts...).
+    #   Available to this agent's mixins and prompt rendering strategies.
+    attr_reader :composable_agents_dir
+
     # 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.

data/lib/composable_agents/ai_agents/agent.rb

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

data/lib/composable_agents/cline/agent.rb

@@ -214,7 +214,7 @@ module ComposableAgents
             find_skill(skill, selected_skills)
           end
           # 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}"
+          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 = logger_debug?
             config.temp_dir_root = "#{agent_tmp_dir}/cline-rb"

data/lib/composable_agents/mixins/resumable.rb

@@ -208,7 +208,7 @@ module ComposableAgents
       # @param step_full_name [String] Step full name
       # @return [String] Corresponding JSON file that stores the step states
       def saved_step_states_json(step_full_name)
-        "#{@composable_agents_dir}/runs/#{@run_id}/#{step_full_name.gsub(/[^\w.]/, '_')}.json"
+        "#{composable_agents_dir}/runs/#{@run_id}/#{step_full_name.gsub(/[^\w.]/, '_')}.json"
       end
 
       # Get saved step states from a given full step name.

data/lib/composable_agents/prompt_driven_agent.rb

@@ -10,6 +10,8 @@ module ComposableAgents
   #
   # Prompt rendering strategies are useful because different prompt-driven agents would benefit from different
   #   prompt formats or structures (JSON, Markdown, explicit ordered lists, in-lining artifacts' contents without tools...).
+  # A strategy is a module that is included in the agent's singleton class when the agent is constructed
+  #   (see PromptRenderingStrategy).
   # This agent automatically records non-rendered conversation (prompts + outputs) in a `conversation` store, part of its state.
   class PromptDrivenAgent < Agent
     # @!group Public API
@@ -42,7 +44,9 @@ module ComposableAgents
     # @param system_instructions [Object, nil] Original instructions for the agent, or nil if no system instructions are needed.
     #   The kind of instructions that can be given are defined by the Instructions's constructor (see Instructions#initialize).
     # @param constraints [String, nil] Constraints to be respected, or nil for the agent's default
-    # @param strategy [Module] The prompt rendering strategy
+    # @param strategy [Module] The prompt rendering strategy.
+    #   Strategies must not define their own constructor: a strategy that can be customized exposes public accessors
+    #   to be set on the agent (see PromptRenderingStrategy::MarkdownHeavyFiles#artifacts_directory=).
     def initialize(
       *args,
       role: nil,
@@ -161,6 +165,10 @@ module ComposableAgents
 
     private
 
+    # @return [Hash{Symbol => Object}, nil] The input artifacts of the current run, or nil if no run has started yet.
+    #   Available to this agent's prompt rendering strategies.
+    attr_reader :input_artifacts
+
     # 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.

data/lib/composable_agents/prompt_rendering_strategy/markdown.rb

@@ -1,5 +1,15 @@
 module ComposableAgents
-  # Collection of prompt rendering strategies that can be used with PromptDrivenAgent's agents
+  # Collection of prompt rendering strategies that can be used with PromptDrivenAgent's agents.
+  # A strategy is a module that is included in the agent's singleton class when the agent is constructed
+  #   (see PromptDrivenAgent#initialize).
+  # Strategies must follow these rules:
+  # - They must not define an #initialize method: strategies don't have any constructor parameter.
+  # - A strategy that can be customized publishes public accessors on the agent, whose defaults are resolved lazily
+  #   from the agent's public API, so that they can be set at any time on a constructed agent
+  #   (see MarkdownHeavyFiles#artifacts_directory).
+  # - They use the agent's accessors (e.g. #name, #role, #objective, #constraints, #input_artifacts,
+  #   #composable_agents_dir) — including its private ones, as strategies are part of the agent — and never access
+  #   its instance variables.
   module PromptRenderingStrategy
     # Render prompt as Markdown documents
     module Markdown
@@ -30,44 +40,44 @@ module ComposableAgents
       end
 
       # Render the system prompt.
-      # The following instance variables are accessible to render the prompt:
-      # - `@input_artifacts`
-      # - `@role`
-      # - `@objective`
-      # - `@constraints`
+      # The following accessors are available to render the prompt:
+      # - `#input_artifacts`
+      # - `#role`
+      # - `#objective`
+      # - `#constraints`
       #
       # @param rendered_instructions [String, nil] The rendered system instructions, or nil if none
       # @return [String] The rendered system prompt
       def render_system_prompt(rendered_instructions)
         sections = []
-        sections << <<~EO_SECTION if @role && !@role.empty?
+        sections << <<~EO_SECTION if role && !role.empty?
           # Role
 
-          #{Utils::Markdown.align_markdown_headers(@role, level: 2).strip}
+          #{Utils::Markdown.align_markdown_headers(role, level: 2).strip}
         EO_SECTION
-        sections << <<~EO_SECTION if @objective && !@objective.empty?
+        sections << <<~EO_SECTION if objective && !objective.empty?
           # Objective
 
-          #{Utils::Markdown.align_markdown_headers(@objective, level: 2).strip}
+          #{Utils::Markdown.align_markdown_headers(objective, level: 2).strip}
         EO_SECTION
         sections << <<~EO_SECTION if rendered_instructions && !rendered_instructions.empty?
           # Instructions
 
           #{Utils::Markdown.align_markdown_headers(rendered_instructions, level: 2).strip}
         EO_SECTION
-        sections << <<~EO_SECTION if @constraints && !@constraints.empty?
+        sections << <<~EO_SECTION if constraints && !constraints.empty?
           # Constraints
 
-          #{Utils::Markdown.align_markdown_headers(@constraints, level: 2).strip}
+          #{Utils::Markdown.align_markdown_headers(constraints, level: 2).strip}
         EO_SECTION
         sections.map(&:strip).join("\n\n")
       end
 
       # Render the user prompt
-      # The following instance variables are accessible to render the prompt:
-      # - `@role`
-      # - `@objective`
-      # - `@constraints`
+      # The following accessors are available to render the prompt:
+      # - `#role`
+      # - `#objective`
+      # - `#constraints`
       #
       # @param rendered_instructions [String, nil] The rendered instructions, or nil if none
       # @param input_artifacts [Hash{Symbol => Object}] The input artifacts content for which we render this prompt, per artifact name

data/lib/composable_agents/prompt_rendering_strategy/markdown_heavy.rb

@@ -47,11 +47,11 @@ module ComposableAgents
       end
 
       # Render the system prompt
-      # The following instance variables are accessible to render the prompt:
-      # - `@input_artifacts`
-      # - `@role`
-      # - `@objective`
-      # - `@constraints`
+      # The following accessors are available to render the prompt:
+      # - `#input_artifacts`
+      # - `#role`
+      # - `#objective`
+      # - `#constraints`
       #
       # @param rendered_instructions [String, nil] The rendered system instructions, or nil if none
       # @return [String] The rendered system prompt
@@ -65,10 +65,10 @@ module ComposableAgents
       end
 
       # Render the user prompt
-      # The following instance variables are accessible to render the prompt:
-      # - `@role`
-      # - `@objective`
-      # - `@constraints`
+      # The following accessors are available to render the prompt:
+      # - `#role`
+      # - `#objective`
+      # - `#constraints`
       #
       # @param rendered_instructions [String, nil] The rendered instructions, or nil if none
       # @param input_artifacts [Hash{Symbol => Object}] The input artifacts content for which we render this prompt, per artifact name

data/lib/composable_agents/prompt_rendering_strategy/markdown_heavy_files.rb

@@ -15,33 +15,46 @@ module ComposableAgents
     # - `#parse_output_artifacts(text)` Parses a text that comes from the agent to retrieve output artifacts from files.
     # - `#artifact_ref(artifact_name) -> String` Returns the absolute path of the artifact file as seen by the assistant.
     #     This can be used to refer to the artifact names properly in the user or system instructions.
-    # The constructor accepts the following extra parameter:
-    # - `artifacts_directory` [String, nil] Directory where artifacts are persisted, or nil to default to
-    #   `#{composable_agents_dir}/artifacts`. Input and output artifacts are persisted in the
-    #   `input` and `output` sub-directories respectively.
+    # Artifacts are persisted in a directory that defaults to `#{composable_agents_dir}/artifacts`, where input and
+    # output artifacts are persisted in its `input` and `output` sub-directories respectively.
+    # Those directories are resolved lazily and created on disk the first time they are needed, so that this strategy
+    # needs no state initialization and no constructor parameter.
+    # The directory can be customized at any time on an agent using this strategy by setting its
+    # #artifacts_directory accessor.
     module MarkdownHeavyFiles
-      # @!group Internal
-
       include MarkdownHeavy
 
-      # Constructor
+      # @!group Public API
+
+      # Get the directory where artifacts are persisted.
+      # Defaults to `#{composable_agents_dir}/artifacts`.
+      # Input and output artifacts are persisted in its `input` and `output` sub-directories respectively.
+      # Those directories are resolved lazily and created on disk the first time they are needed.
       #
-      # @param artifacts_directory [String, nil] Directory where artifacts are persisted, or nil to default to
+      # @return [String] The directory where artifacts are persisted
+      def artifacts_directory
+        @artifacts_directory || "#{composable_agents_dir}/artifacts"
+      end
+
+      # Set the directory where artifacts are persisted (see #artifacts_directory).
+      # Already resolved input and output artifacts directories are reset, so that they follow the new directory
+      #   the next time they are needed.
+      #
+      # @param directory [String, nil] The directory where artifacts are persisted, or nil to default to
       #   `#{composable_agents_dir}/artifacts`
-      def initialize(*args, artifacts_directory: nil, **kwargs)
-        super(*args, **kwargs)
-        artifacts_directory ||= "#{@composable_agents_dir}/artifacts"
-        @input_artifacts_directory = File.join(artifacts_directory, 'input')
-        @output_artifacts_directory = File.join(artifacts_directory, 'output')
-        FileUtils.mkdir_p(@input_artifacts_directory)
-        FileUtils.mkdir_p(@output_artifacts_directory)
+      def artifacts_directory=(directory)
+        @artifacts_directory = directory
+        @input_artifacts_directory = nil
+        @output_artifacts_directory = nil
       end
 
+      # @!group Internal
+
       # Render the user prompt
-      # The following instance variables are accessible to render the prompt:
-      # - `@role`
-      # - `@objective`
-      # - `@constraints`
+      # The following accessors are available to render the prompt:
+      # - `#role`
+      # - `#objective`
+      # - `#constraints`
       #
       # @param rendered_instructions [String, nil] The rendered instructions, or nil if none
       # @param input_artifacts [Hash{Symbol => Object}] The input artifacts content for which we render this prompt, per artifact name
@@ -134,6 +147,24 @@ module ComposableAgents
 
       private
 
+      # Get the directory where input artifacts are persisted.
+      # Created on disk the first time it is needed.
+      # Memoized.
+      #
+      # @return [String] The directory where input artifacts are persisted
+      def input_artifacts_directory
+        @input_artifacts_directory ||= File.join(artifacts_directory, 'input').tap { |dir| FileUtils.mkdir_p(dir) }
+      end
+
+      # Get the directory where output artifacts are persisted.
+      # Created on disk the first time it is needed.
+      # Memoized.
+      #
+      # @return [String] The directory where output artifacts are persisted
+      def output_artifacts_directory
+        @output_artifacts_directory ||= File.join(artifacts_directory, 'output').tap { |dir| FileUtils.mkdir_p(dir) }
+      end
+
       # Render the input artifacts concept section of the system prompt.
       #
       # @param input_contracts [Hash{Symbol => Hash{Symbol => Object}}] The normalized input artifacts contracts
@@ -218,7 +249,7 @@ module ComposableAgents
       # @return [String] The absolute path of the input artifact file
       def input_artifact_path(artifact_name)
         File.join(
-          @input_artifacts_directory,
+          input_artifacts_directory,
           "#{artifact_name}#{artifact_extension(normalized_input_artifacts_contracts.dig(artifact_name, :type))}"
         )
       end
@@ -229,7 +260,7 @@ module ComposableAgents
       # @return [String] The absolute path of the output artifact file
       def output_artifact_path(artifact_name)
         File.join(
-          @output_artifacts_directory,
+          output_artifacts_directory,
           "#{artifact_name}#{artifact_extension(normalized_output_artifacts_contracts.dig(artifact_name, :type))}"
         )
       end

data/lib/composable_agents/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: composable_agents
 version: !ruby/object:Gem::Version
-  version: 3.7.0
+  version: 3.7.2
 platform: ruby
 authors:
 - Muriel Salvan