active_harness 0.3.8 → 0.3.10

data/lib/active_harness/request.rb

@@ -17,7 +17,9 @@ module ActiveHarness
         memory:  nil,
         models:  nil,
         token:   nil,
-        stream:  nil
+        stream:  nil,
+        messages: nil,
+        tools:    nil
       )
         new(
           input:   input,
@@ -26,7 +28,9 @@ module ActiveHarness
           memory:  memory,
           models:  models,
           token:   token,
-          stream:  stream
+          stream:  stream,
+          messages: messages,
+          tools:    tools
         ).call
       end
 
@@ -54,7 +58,9 @@ module ActiveHarness
     attr_accessor :input,
                   :context,
                   :params,
-                  :memory
+                  :memory,
+                  :messages,
+                  :tools
     attr_reader   :result,
                   :token,
                   :stream
@@ -71,9 +77,13 @@ module ActiveHarness
       memory:  nil,
       models:  nil,
       token:   nil,
-      stream:  nil
+      stream:  nil,
+      messages: nil,
+      tools:    nil
     )
       @input           = input
+      @messages        = messages
+      @tools           = tools
       @config          = self.class.request_config
       normalize_input!
       @context         = context
@@ -91,11 +101,18 @@ module ActiveHarness
     # Optionally accepts input and stream callback inline:
     #   request.call("What is the capital of Japan?")
     #   request.call("...", stream: ->(token) { print token })
-    def call(input = nil, token: nil, stream: nil)
+    #
+    # Agent extension: pass +messages:+ (a conversation instead of a single input)
+    # and +tools:+ (neutral tool schemas). The model may then answer with
+    # +result.tool_calls+; nothing is executed here — running tools is the Agent's job.
+    def call(input = nil, token: nil, stream: nil, messages: nil, tools: nil)
       if input
         @input = input
         normalize_input!
       end
+      @messages = messages if messages
+      @tools    = tools    if tools
+      @input    = last_user_content(@messages) if @input.nil? && @messages
       @token  = token  if token
       @stream = stream if stream
       fire(:before_call)
@@ -147,7 +164,9 @@ module ActiveHarness
 
     def build_result(response, entry, attempts, elapsed)
       raw        = response[:content]
-      processed  = parse_output(raw)
+      tool_calls = response[:tool_calls]
+      tool_calls = nil if tool_calls && tool_calls.empty?
+      processed  = tool_calls ? raw : parse_output(raw)
       raw_usage  = response[:usage]
       model_cost = lookup_model_cost(entry)
 
@@ -160,10 +179,23 @@ module ActiveHarness
         model_list:     model_list,
         attempts:       attempts,
         execution_time: elapsed,
-        usage:          build_usage(raw_usage, model_cost)
+        usage:          build_usage(raw_usage, model_cost),
+        tool_calls:     tool_calls,
+        message:        tool_calls || @messages ? assistant_message(raw, tool_calls) : nil
       )
     end
 
+    def assistant_message(content, tool_calls)
+      msg = { role: :assistant, content: content.to_s }
+      msg[:tool_calls] = tool_calls if tool_calls
+      msg
+    end
+
+    def last_user_content(messages)
+      last = Array(messages).reverse.find { |m| (m[:role] || m["role"]).to_s == "user" }
+      last && (last[:content] || last["content"])
+    end
+
     def build_model_info(entry, model_cost)
       pricing = if model_cost&.input_per_million && model_cost&.output_per_million
         ModelPricing.new(

data/lib/active_harness/result.rb

@@ -49,6 +49,8 @@ module ActiveHarness
   #   result.attempts         — Array of failed attempt entries before success
   #   result.execution_time   — wall-clock seconds for the successful call
   #   result.usage            — UsageInfo (tokens + cost), nil for streaming without usage
+  #   result.tool_calls       — Array of { id:, name:, arguments: } the model asked for (nil when none)
+  #   result.message          — the assistant message in neutral shape, ready to append to a messages list
   Result = Struct.new(
     :input,
     :output,
@@ -59,6 +61,8 @@ module ActiveHarness
     :attempts,
     :execution_time,
     :usage,           # UsageInfo or nil
+    :tool_calls,      # Array<Hash> or nil
+    :message,         # { role: :assistant, content:, tool_calls: } or nil
     keyword_init: true
   )
 end

data/lib/active_harness/tool/path_policy.rb

@@ -0,0 +1,28 @@
+module ActiveHarness
+  class Tool
+    # Reusable path checks — implemented once, correctly (symlinks, "..", the
+    # trailing-slash prefix bug). The including tool must define ALLOWED_PATHS;
+    # a missing constant raises NameError, which fails closed (an :error result).
+    #
+    #   class LsTool < ActiveHarness::Tool
+    #     include ActiveHarness::Tool::PathPolicy
+    #     ALLOWED_PATHS = %w[/srv/app/workspace].freeze
+    #
+    #     step(:resolve_path, transform: true) { |input| input.merge(path: safe_path!(input[:path])) }
+    #   end
+    module PathPolicy
+      # Returns a canonical absolute path inside ALLOWED_PATHS, or raises Denied.
+      def safe_path!(path)
+        deny!("path must not contain NUL") if path.to_s.include?("\0")
+
+        real  = File.realpath(File.expand_path(path.to_s)) # follows symlinks
+        roots = self.class::ALLOWED_PATHS.map { |r| File.realpath(r) }
+        ok    = roots.any? { |r| real == r || real.start_with?(r + File::SEPARATOR) }
+        deny!("#{path} is outside allowed directories", detail: "resolved to #{real}") unless ok
+        real
+      rescue Errno::ENOENT
+        deny!("#{path} does not exist")
+      end
+    end
+  end
+end

data/lib/active_harness/tool.rb

@@ -0,0 +1,342 @@
+require "json"
+
+module ActiveHarness
+  # One step of a tool call, as recorded in ToolResult#steps.
+  #
+  #   name    — step name (:perform for the action itself)
+  #   status  — :ok | :denied | :error
+  #   message — safe text; the ONLY thing the model may see
+  #   detail  — internals (paths, policy names, exception class) for traces/logs only
+  #   ms      — duration in milliseconds
+  StepResult = Struct.new(:name, :status, :message, :detail, :ms, keyword_init: true)
+
+  # Outcome of Tool.call. Never an exception for expected failures.
+  #
+  #   status           — :ok | :denied | :error
+  #   input            — arguments as the tool received them
+  #   output           — value returned by +perform+ (nil unless :ok)
+  #   failed_step      — StepResult of the step that stopped the call (nil when :ok)
+  #   steps            — StepResult of every step that ran
+  #   outcome_unknown  — true when the tool reported that a side effect may have happened
+  ToolResult = Struct.new(:status, :input, :output, :failed_step, :steps, :outcome_unknown, keyword_init: true) do
+    def ok?;      status == :ok;      end
+    def denied?;  status == :denied;  end
+    def error?;   status == :error;   end
+
+    # Text for the `tool` message sent back to the model.
+    def model_message
+      case status
+      when :ok
+        output.is_a?(String) ? output : JSON.generate(output)
+      else
+        failed_step&.message.to_s
+      end
+    end
+
+    def execution_time
+      (steps || []).sum { |s| s.ms.to_i } / 1000.0
+    end
+  end
+
+  # A privileged action behind named, ordered steps (checks and transforms).
+  # The model never gets a shell — it can only call tools you wrote, and every
+  # call passes through your checks first.
+  #
+  #   class LsTool < ActiveHarness::Tool
+  #     tool_scope  :os
+  #     tool_name   "ls"
+  #     description "List files in a directory"
+  #     param :path, "Directory to list"
+  #
+  #     step(:no_hidden) { |input| deny!("hidden dirs are off limits") if input[:path].include?("/.") }
+  #
+  #     def perform(input)
+  #       Dir.children(input[:path]).first(200)
+  #     end
+  #   end
+  #
+  #   LsTool.call(input: { path: "/srv" }, context: { user: current_user }) # => ToolResult
+  class Tool
+    # Raised (via #deny!) from any step or hook: the call is refused. +message+ is
+    # safe for the model; +detail+ stays in the trace.
+    class Denied < StandardError
+      attr_reader :detail
+
+      def initialize(message = nil, detail: nil)
+        super(message)
+        @detail = detail
+      end
+    end
+
+    # Raised (via #unknown_outcome!) when a side effect may or may not have happened
+    # (e.g. a timeout after a write was sent). Result: status :error, outcome_unknown: true.
+    # Deliberately NOT a Denied, so it never matches `rescue Denied`.
+    class UnknownOutcome < StandardError
+      attr_reader :detail
+
+      def initialize(message = nil, detail: nil)
+        super(message)
+        @detail = detail
+      end
+    end
+
+    Step    = Struct.new(:name, :block, :transform)
+    PERFORM = Step.new(:perform, nil, true)
+
+    VALID_HOOKS      = %i[before_step after_step before_perform after_perform].freeze
+    VALID_STEP_HOOKS = %i[before_step after_step].freeze
+
+    GENERIC_ERROR_MESSAGE   = "tool failed, try another approach or finish".freeze
+    UNKNOWN_OUTCOME_MESSAGE = "result unknown, verify before retrying".freeze
+
+    # -------------------------------------------------------------------------
+    # Class-level DSL
+    # -------------------------------------------------------------------------
+    class << self
+      # --- what the model sees ---
+
+      # Required namespace: :os, :web, :ruby ... Full name is "tool_scope::tool_name".
+      # Both are explicit on purpose: the name the model sees must not change when a class is renamed.
+      def tool_scope(value = nil)
+        value ? @tool_scope = value.to_sym : @tool_scope
+      end
+
+      # Required: "ls", "fetch_url" ...
+      def tool_name(value = nil)
+        value ? @tool_name = value.to_s : @tool_name
+      end
+
+      def full_name
+        raise ArgumentError, "#{name || 'Tool'} must declare a tool_scope (e.g. `tool_scope :os`)" unless tool_scope
+        raise ArgumentError, "#{name || 'Tool'} must declare a tool_name (e.g. `tool_name \"ls\"`)" unless tool_name
+
+        "#{tool_scope}::#{tool_name}"
+      end
+
+      # Name on the wire: providers allow only [a-zA-Z0-9_-] in function names.
+      def wire_name
+        full_name.sub("::", "__")
+      end
+
+      def description(value = nil)
+        value ? @description = value : @description
+      end
+
+      # Declares one argument for the model.
+      #
+      #   param :path, "Directory to list"                      # type: :string, required: true
+      #   param :limit, "Max entries", type: :integer, required: false
+      #   param :kind, "Entry kind", enum: %w[file dir]
+      def param(name, description, type: :string, required: true, enum: nil)
+        params << { name: name.to_sym, description: description, type: type, required: required, enum: enum }.reject { |_, v| v.nil? }
+      end
+
+      def params
+        @params ||= []
+      end
+
+      # Argument list (same data as +param+ builds); may be overridden by hand.
+      def schema
+        params
+      end
+
+      # Provider-neutral function schema; providers map it to their wire format.
+      #   { name: "os__ls", description: "...", parameters: { type: "object", properties: {...}, required: [...] } }
+      def to_schema
+        props = {}
+        required = []
+        schema.each do |arg|
+          prop = { type: (arg[:type] || :string).to_s }
+          prop[:description] = arg[:description] if arg[:description]
+          prop[:enum]        = arg[:enum]        if arg[:enum]
+          props[arg[:name].to_s] = prop
+          required << arg[:name].to_s if arg.fetch(:required, true)
+        end
+
+        {
+          name:        wire_name,
+          description: description.to_s,
+          parameters:  { type: "object", properties: props, required: required }
+        }
+      end
+
+      # Checks arguments against +schema+. Returns an error message String or nil.
+      # Used by the Agent before running the tool (tools themselves get raw input).
+      def validate_input(input)
+        return "arguments must be an object" unless input.is_a?(Hash)
+
+        known = schema.map { |a| a[:name].to_sym }
+        extra = input.keys.map(&:to_sym) - known
+        return "unknown argument: #{extra.first}" unless extra.empty?
+
+        schema.each do |arg|
+          key   = arg[:name].to_sym
+          value = input.key?(key) ? input[key] : input[key.to_s]
+          return "missing required argument: #{key}" if arg.fetch(:required, true) && value.nil?
+          if arg[:enum] && !value.nil? && !arg[:enum].include?(value)
+            return "invalid value for #{key}: expected one of #{arg[:enum].join(', ')}"
+          end
+        end
+        nil
+      end
+
+      # --- what the model does NOT see: ordered, named steps ---
+
+      # step :name do |input| ... end        — a block
+      # step :name                           — calls the instance method of the same name
+      # step :name, transform: true { ... }  — the return value replaces the payload for later steps and perform
+      def step(name, transform: false, &block)
+        steps << Step.new(name.to_sym, block, transform)
+      end
+
+      def steps
+        @steps ||= []
+      end
+
+      def hooks
+        @hooks ||= {}
+      end
+
+      def step_hooks
+        @step_hooks ||= {}
+      end
+
+      # Hooks run through instance_exec on the tool instance (they see context, payload, output).
+      #
+      #   on :before_step,    :resolve_path do |payload| ... end   # per-step form
+      #   on :before_step   do |step_name, payload| ... end
+      #   on :after_step    do |step_name, step_result| ... end
+      #   on :before_perform do |payload| ... end
+      #   on :after_perform  do |output| ... end
+      def on(event, step_name = nil, &block)
+        if step_name
+          raise ArgumentError, "Per-step hooks support: #{VALID_STEP_HOOKS.join(', ')}. Got :#{event}" unless VALID_STEP_HOOKS.include?(event)
+
+          ((step_hooks[step_name.to_sym] ||= {})[event] ||= []) << block
+        else
+          raise ArgumentError, "Unknown Tool hook :#{event}. Valid: #{VALID_HOOKS.join(', ')}" unless VALID_HOOKS.include?(event)
+
+          (hooks[event] ||= []) << block
+        end
+      end
+
+      def before(event, step_name = nil, &block)
+        on(:"before_#{event}", step_name, &block)
+      end
+
+      def after(event, step_name = nil, &block)
+        on(:"after_#{event}", step_name, &block)
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@tool_scope, @tool_scope)
+        subclass.instance_variable_set(:@steps, steps.dup)
+        subclass.instance_variable_set(:@params, params.map(&:dup))
+        subclass.instance_variable_set(:@hooks, hooks.each_with_object({}) { |(k, v), h| h[k] = v.dup })
+        subclass.instance_variable_set(:@step_hooks, step_hooks.each_with_object({}) { |(k, v), h| h[k] = v.transform_values(&:dup) })
+      end
+
+      # Same style as Request.call.
+      def call(input:, context: {})
+        new(context: context).call(input)
+      end
+    end
+
+    include Core::HookRunner
+
+    # -------------------------------------------------------------------------
+    # Instance API
+    # -------------------------------------------------------------------------
+    attr_reader   :context
+    attr_accessor :payload, :output
+
+    def initialize(context: {})
+      @context = context
+    end
+
+    # Entry point used by the Agent loop. Never raises for expected failures.
+    def call(input)
+      @payload = input
+      @output  = nil
+      steps    = []
+
+      (self.class.steps + [PERFORM]).each do |step|
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        status, message, detail, unknown = :ok, nil, nil, false
+
+        begin
+          fire(:before_step, step.name, @payload)
+          fire_step(:before_step, step.name, @payload)
+          fire(:before_perform, @payload) if step.name == :perform
+
+          value = run_step(step)
+          @payload = value if step.transform
+
+          if step.name == :perform
+            @output = value
+            fire(:after_perform, @output)
+          end
+        rescue Denied => e
+          status, message, detail = :denied, e.message, e.detail
+        rescue UnknownOutcome => e
+          status, message, detail, unknown = :error, UNKNOWN_OUTCOME_MESSAGE, e.detail || e.message, true
+        rescue StandardError => e
+          status, message, detail = :error, GENERIC_ERROR_MESSAGE, "#{e.class}: #{e.message}"
+        end
+
+        steps << StepResult.new(name: step.name, status: status, message: message, detail: detail, ms: elapsed_ms(started))
+        fire(:after_step, step.name, steps.last)
+        fire_step(:after_step, step.name, steps.last)
+
+        next if status == :ok
+
+        return ToolResult.new(status: status, input: input, failed_step: steps.last, steps: steps, outcome_unknown: unknown)
+      end
+
+      ToolResult.new(status: :ok, input: input, output: @output, steps: steps, outcome_unknown: false)
+    end
+
+    # The action itself. Always the last step; its return value is the output.
+    def perform(_input)
+      raise NotImplementedError, "#{self.class.name} must implement #perform"
+    end
+
+    # Refuse the call. +msg+ is shown to the model; +detail+ only goes to the trace.
+    def deny!(msg, detail: nil)
+      raise Denied.new(msg, detail: detail)
+    end
+
+    # The side effect may have happened — the model is told to verify before retrying.
+    def unknown_outcome!(msg = nil, detail: nil)
+      raise UnknownOutcome.new(msg || "unknown outcome", detail: detail)
+    end
+
+    private
+
+    def run_step(step)
+      if step.name == :perform
+        perform(@payload)
+      elsif step.block
+        instance_exec(@payload, &step.block)
+      else
+        send(step.name, @payload)
+      end
+    end
+
+    def fire(event, *args)
+      run_hooks(self.class.hooks, event, *args)
+    end
+
+    # Per-step hook: receives only the data, not the step name.
+    def fire_step(event, step_name, data)
+      run_hooks(self.class.step_hooks[step_name] || {}, event, data)
+    end
+
+    def elapsed_ms(started)
+      ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round
+    end
+  end
+end
+
+require_relative "tool/path_policy"

data/lib/active_harness/tribunal/hooks.rb

@@ -75,7 +75,7 @@ module ActiveHarness
     def fire(event, *args)
       run_hook(event, *args)
       @stream&.call(:tribunal, event, *args)
-    rescue IOError, ActionController::Live::ClientDisconnected
+    rescue ClientGone
       nil
     end
 

data/lib/active_harness.rb

@@ -6,6 +6,7 @@ require_relative "active_harness/http/client"
 require_relative "active_harness/http/streaming_client"
 require_relative "active_harness/http/retry_policy"
 require_relative "active_harness/providers/base"
+require_relative "active_harness/providers/tool_calling"
 require_relative "active_harness/providers/openai"
 require_relative "active_harness/providers/openrouter"
 require_relative "active_harness/providers/groq"
@@ -37,11 +38,13 @@ require_relative "active_harness/memory"
 require_relative "active_harness/request"
 require_relative "active_harness/tribunal"
 require_relative "active_harness/pipeline"
+require_relative "active_harness/tool"
+require_relative "active_harness/agent"
 
 require_relative "active_harness/railtie" if defined?(Rails::Railtie)
 
 module ActiveHarness
-  VERSION = "0.3.8"
+  VERSION = "0.3.10"
 
   class << self
     # Configure ActiveHarness.

data/lib/generators/active_harness/agent/agent_generator.rb

@@ -0,0 +1,16 @@
+require "rails/generators"
+
+module ActiveHarness
+  module Generators
+    class AgentGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an ActiveHarness agent in app/ai/agents/"
+
+      def create_agent
+        template "agent.rb.tt",
+                 "app/ai/agents/#{file_name}_agent.rb"
+      end
+    end
+  end
+end

data/lib/generators/active_harness/agent/templates/agent.rb.tt

@@ -0,0 +1,14 @@
+class <%= class_name %>Agent < ActiveHarness::Agent
+  # The Request that talks to the model each turn (owns model chain, retries, fallback).
+  request <%= class_name %>Request
+
+  # The only tools the model may call (default deny: anything else is "unknown tool").
+  # tools ExampleTool
+
+  # Optional: judge the final answer; without it the first answer without tool calls ends the run.
+  # goal <%= class_name %>Goal
+
+  # Hard limits so a looping model cannot run or spend forever.
+  max_turns 10
+  max_cost  0.50
+end

data/lib/generators/active_harness/goal/goal_generator.rb

@@ -0,0 +1,16 @@
+require "rails/generators"
+
+module ActiveHarness
+  module Generators
+    class GoalGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates an ActiveHarness goal check in app/ai/goals/"
+
+      def create_goal
+        template "goal.rb.tt",
+                 "app/ai/goals/#{file_name}_goal.rb"
+      end
+    end
+  end
+end

data/lib/generators/active_harness/goal/templates/goal.rb.tt

@@ -0,0 +1,14 @@
+# A goal check judges the agent's final answer: override #call(candidate:, goal:, state:)
+# to return a GoalCheckResult. Plug it in with `goal <%= class_name %>Goal`.
+# Prefer deterministic checks (tests, schemas, counts) to asking an LLM.
+class <%= class_name %>Goal < ActiveHarness::GoalCheck
+  def call(candidate:, goal:, state:)
+    if candidate.to_s.strip.empty?
+      # :continue sends the feedback to the model for another turn (up to max_goal_retries).
+      # Other statuses: :achieved, :replan, :needs_input, :failed.
+      ActiveHarness::GoalCheckResult.new(status: :continue, feedback: "The answer is empty. Answer the question.")
+    else
+      ActiveHarness::GoalCheckResult.new(status: :achieved)
+    end
+  end
+end

data/lib/generators/active_harness/install/install_generator.rb

@@ -3,16 +3,26 @@ require "rails/generators"
 module ActiveHarness
   module Generators
     class InstallGenerator < Rails::Generators::Base
-      desc "Creates the app/ai/ directory structure for ActiveHarness"
+      desc "Creates the app/ai/ directory structure for ActiveHarness.\n" \
+           "Safe to re-run: existing files are never touched, only missing example files are added."
 
       source_root File.expand_path("templates", __dir__)
 
-      APP_AI_DIRS = %w[requests prompts tribunals pipelines memory].freeze
+      ROUTES = {
+        "ai/agent"          => 'post "ai/agent",          to: "ai_support#agent" # not "request" — would override ActionController::Base#request',
+        "ai/request_memory" => 'post "ai/request_memory", to: "ai_support#request_memory"',
+        "ai/tribunal"       => 'post "ai/tribunal",       to: "ai_support#tribunal"',
+        "ai/pipeline"       => 'post "ai/pipeline",       to: "ai_support#pipeline"',
+        "ai/files_agent"    => 'post "ai/files_agent",    to: "ai_support#files_agent"',
+        "ai/request_stream" => 'get  "ai/request_stream", to: "ai_support#request_stream"'
+      }.freeze
+
+      APP_AI_DIRS = %w[concerns requests prompts tribunals pipelines memory agents tools goals].freeze
 
       def create_structure
         APP_AI_DIRS.each do |dir|
           empty_directory "app/ai/#{dir}"
-          copy_templates_if_empty(dir)
+          copy_missing_templates(dir)
         end
       end
 
@@ -24,14 +34,6 @@ module ActiveHarness
                   "config/initializers/active_harness.rb"
       end
 
-      def create_initializer
-        target = File.join(destination_root, "config", "initializers", "active_harness.rb")
-        return if File.exist?(target)
-
-        copy_file "initializers/active_harness.rb",
-                  "config/initializers/active_harness.rb"
-      end
-
       def copy_controller
         target = File.join(destination_root, "app", "controllers", "ai_support_controller.rb")
         return if File.exist?(target)
@@ -40,29 +42,32 @@ module ActiveHarness
                   "app/controllers/ai_support_controller.rb"
       end
 
+      # Adds only the routes that are not in config/routes.rb yet, so re-running is harmless.
       def inject_routes
-        route <<~ROUTES.strip
-          # ActiveHarness — AI support endpoints
-          post "ai/agent",          to: "ai_support#agent" # not "request" — would override ActionController::Base#request
-          post "ai/request_memory", to: "ai_support#request_memory"
-          post "ai/tribunal",       to: "ai_support#tribunal"
-          post "ai/pipeline",       to: "ai_support#pipeline"
-          get  "ai/request_stream", to: "ai_support#request_stream"
-        ROUTES
+        routes_file = File.join(destination_root, "config", "routes.rb")
+        existing    = File.exist?(routes_file) ? File.read(routes_file) : ""
+        missing     = ROUTES.reject { |path, _line| existing.include?(%("#{path}")) }
+        return if missing.empty?
+
+        route(["# ActiveHarness — AI support endpoints", *missing.map { |_path, line| line }].join("\n"))
       end
 
       private
 
-      def copy_templates_if_empty(dir)
-        target_dir = File.join(destination_root, "app", "ai", dir)
-        return if Dir.glob(File.join(target_dir, "*.rb")).any?
-
+      # Per-file, never overwrites: a template is copied only when its target does not exist.
+      # Examples depend on each other (agent -> request/tools/goal/concerns), so a missing
+      # piece is added even when its directory already holds the user's own files.
+      def copy_missing_templates(dir)
         template_dir = File.join(self.class.source_root, dir)
         return unless Dir.exist?(template_dir)
 
         Dir[File.join(template_dir, "*.rb")].sort.each do |tpl|
-          copy_file File.join(dir, File.basename(tpl)),
-                    File.join("app", "ai", dir, File.basename(tpl))
+          relative = File.join("app", "ai", dir, File.basename(tpl))
+          if File.exist?(File.join(destination_root, relative))
+            say_status :skip, "#{relative} (exists)", :yellow
+          else
+            copy_file File.join(dir, File.basename(tpl)), relative
+          end
         end
       end
     end