ruby_llm-agents 3.12.0 → 3.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5e29829dcedb6a67dd1d9e55c7a45ead560e5da2fc0f75ffd04c97026e8d5b90
-  data.tar.gz: 9c2981a6eed9459f2c7d56c47f6ff5ddcdd282bc90729ace04b8eca4f83e9e55
+  metadata.gz: 5fc64ee9b7db541e40c144d3b8007c0967f7ad63a7b5c404079d7c4c3398a646
+  data.tar.gz: 1c5b0d4c8c55390cfb5bee3ad394b47f4cae44dbd0452c5135c6ad7e7ac66a0b
 SHA512:
-  metadata.gz: 86ed72b1e799b64259b83588ac9c9111d04539eb7225e65d517332d22ed671436214255ec0127fdcff4ef65fe283683219e88b67a956c6270a7b6a0140937a27
-  data.tar.gz: b532f5a4a47814ed19a9929b06e506b56af651d8d1be65348c68b61aa78dc48f771c89c8d667dac06860d88283fee3a890b8d39afc4d11f5e6905ceca396c136
+  metadata.gz: 9c187e97882d3b4cf91dc98db12004d809db61a04bf95463aa32f1fa64b53a54d7f0800dfe105e0e6c5bf541b79bcdbe8f3d7537767b9c0d9814095f8fe6889d
+  data.tar.gz: 63b31bfcfcd27acaded706b78cfa96db5825e98ebd6f4a7fe4b2786ed0f15d048c706fdd157c4364618388816ab739a8c0dac34c773bcfaf0f67d9dc90397766

data/app/controllers/ruby_llm/agents/executions_controller.rb

@@ -203,6 +203,11 @@ module RubyLLM
         model_ids = parse_array_param(:model_ids)
         scope = scope.where(model_id: model_ids) if model_ids.any?
 
+        # Apply tenant filter (multi-select). Narrows further within any
+        # auto-scope already applied by tenant_scoped_executions.
+        tenant_ids = parse_array_param(:tenant_ids)
+        scope = scope.where(tenant_id: tenant_ids) if tenant_ids.any?
+
         # Apply retries filter (show only executions with multiple attempts)
         scope = scope.where("attempts_count > 1") if params[:has_retries].present?
 

data/app/models/ruby_llm/agents/execution.rb

@@ -79,12 +79,24 @@ module RubyLLM
         foreign_key: :execution_id, dependent: :destroy
 
       # Delegations so existing code keeps working transparently
-      delegate :system_prompt, :user_prompt, :assistant_prompt, :response, :error_message,
+      delegate :system_prompt, :user_prompt, :assistant_prompt, :response,
         :messages_summary, :tool_calls, :attempts, :fallback_chain,
         :parameters, :routed_to, :classification_result,
         :cached_at, :cache_creation_tokens,
         to: :detail, prefix: false, allow_nil: true
 
+      # Error message reader that survives soft purge.
+      #
+      # Prefers detail.error_message when the detail row still exists, otherwise
+      # falls back to the truncated copy stored in metadata by the retention
+      # job. This lets error-rate trend analysis continue working past the
+      # soft-purge window.
+      #
+      # @return [String, nil]
+      def error_message
+        detail&.error_message || metadata&.dig("error_message")
+      end
+
       # Validations
       validates :agent_type, :model_id, :started_at, presence: true
       validates :status, inclusion: {in: statuses.keys}
@@ -215,6 +227,44 @@ module RubyLLM
         metadata&.dig("rate_limited") == true
       end
 
+      # Returns the response payload as a Hash, regardless of how agents wrote it.
+      #
+      # The `execution_details.response` column is declared as JSON, but agents
+      # may write plain strings (chat text), arrays (embeddings), or nil. Views
+      # that want to look up specific keys (audio_url, image_url, etc.) need a
+      # Hash they can safely `.dig` into. This reader returns an empty hash when
+      # the stored response isn't a Hash, so callers don't need type guards.
+      #
+      # @return [Hash] Parsed response hash, or empty hash if not hash-shaped
+      def response_hash
+        raw = response
+        raw.is_a?(Hash) ? raw : {}
+      end
+
+      # Returns whether this execution has had its detail payload soft-purged.
+      #
+      # Soft-purged executions retain all analytics columns (cost, tokens,
+      # timing, status) but the large payloads (prompts, responses, tool
+      # calls, attempts) stored in execution_details and tool_executions
+      # have been destroyed by the retention job.
+      #
+      # @return [Boolean] true if the retention job has soft-purged this execution
+      def soft_purged?
+        metadata&.key?("soft_purged_at") == true
+      end
+
+      # Returns when this execution was soft-purged, if ever.
+      #
+      # @return [Time, nil] Parsed timestamp or nil if not soft-purged
+      def soft_purged_at
+        raw = metadata&.dig("soft_purged_at")
+        return nil if raw.blank?
+
+        Time.iso8601(raw)
+      rescue ArgumentError
+        nil
+      end
+
       # Convenience accessors for niche fields stored in metadata JSON
       %w[span_id response_cache_key fallback_reason].each do |field|
         define_method(field) { metadata&.dig(field) }

data/app/views/ruby_llm/agents/agents/_config_agent.html.erb

@@ -111,12 +111,16 @@
 
           <div class="flex items-center gap-2 pt-2">
             <button type="submit" class="text-[10px] px-2 py-0.5 rounded bg-gray-800 dark:bg-gray-200 text-white dark:text-gray-900 hover:bg-gray-700 dark:hover:bg-gray-300 transition-colors">save overrides</button>
-            <% if has_overrides %>
-              <%= link_to "reset all", ruby_llm_agents.reset_overrides_agent_path(@agent_type),
-                    method: :delete,
-                    class: "text-[10px] text-red-500 hover:text-red-400 transition-colors",
-                    data: { confirm: "Remove all dashboard overrides for this agent?" } %>
-            <% end %>
+          </div>
+        <% end %>
+
+        <% if has_overrides %>
+          <div class="mt-1.5">
+            <%= button_to "reset all", ruby_llm_agents.reset_overrides_agent_path(@agent_type),
+                  method: :delete,
+                  class: "text-[10px] text-red-500 hover:text-red-400 transition-colors",
+                  form: { style: "display:inline" },
+                  data: { turbo_confirm: "Remove all dashboard overrides for this agent?" } %>
           </div>
         <% end %>
       </div>

data/app/views/ruby_llm/agents/agents/show.html.erb

@@ -8,10 +8,11 @@
   <div class="flex items-center gap-2 px-3 py-1.5 mb-4 rounded border border-yellow-300 dark:border-yellow-700 bg-yellow-50 dark:bg-yellow-900/20 font-mono text-xs text-yellow-700 dark:text-yellow-400">
     <svg class="w-3.5 h-3.5 flex-shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-2.5L13.732 4c-.77-.833-1.964-.833-2.732 0L4.082 16.5c-.77.833.192 2.5 1.732 2.5z"></path></svg>
     <span>dashboard overrides active: <strong><%= @config[:active_overrides].keys.join(", ") %></strong></span>
-    <%= link_to "reset", ruby_llm_agents.reset_overrides_agent_path(@agent_type),
+    <%= button_to "reset", ruby_llm_agents.reset_overrides_agent_path(@agent_type),
           method: :delete,
           class: "ml-auto text-yellow-600 dark:text-yellow-500 hover:text-yellow-800 dark:hover:text-yellow-300",
-          data: { confirm: "Remove all dashboard overrides?" } %>
+          form: { style: "display:inline" },
+          data: { turbo_confirm: "Remove all dashboard overrides?" } %>
   </div>
 <% end %>
 
@@ -293,8 +294,8 @@
   <% end %>
 <% end %>
 
-<!-- ── config (non-agent types only) ── -->
-<% if @config && @agent_type_kind && @agent_type_kind != "agent" %>
+<!-- ── config ── -->
+<% if @config && @agent_type_kind %>
   <div class="flex items-center gap-3 mt-6 mb-3">
     <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">config</span>
     <div class="flex-1 border-t border-gray-200 dark:border-gray-800"></div>

data/app/views/ruby_llm/agents/executions/_audio_player.html.erb

@@ -1,5 +1,5 @@
 <%
-  response = @execution.response || {}
+  response = @execution.response_hash
   audio_src = response["audio_url"] || response[:audio_url] ||
               response["audio_data_uri"] || response[:audio_data_uri]
   audio_format = response["format"] || response[:format] ||

data/app/views/ruby_llm/agents/executions/_filters.html.erb

@@ -3,14 +3,15 @@
   selected_agents = params[:agent_types].present? ? (params[:agent_types].is_a?(Array) ? params[:agent_types] : params[:agent_types].split(",")) : []
   selected_statuses = params[:statuses].present? ? (params[:statuses].is_a?(Array) ? params[:statuses] : params[:statuses].split(",")) : []
   selected_models = params[:model_ids].present? ? (params[:model_ids].is_a?(Array) ? params[:model_ids] : params[:model_ids].split(",")) : []
+  selected_tenants = params[:tenant_ids].present? ? (params[:tenant_ids].is_a?(Array) ? params[:tenant_ids] : params[:tenant_ids].split(",")) : []
 
-  has_filters = selected_agents.any? || selected_statuses.any? || params[:days].present? || selected_models.any? || params[:tenant_id].present?
+  has_filters = selected_agents.any? || selected_statuses.any? || params[:days].present? || selected_models.any? || selected_tenants.any?
   active_filter_count = [
     selected_agents.any? ? 1 : 0,
     selected_statuses.any? ? 1 : 0,
     params[:days].present? ? 1 : 0,
     selected_models.any? ? 1 : 0,
-    params[:tenant_id].present? ? 1 : 0
+    selected_tenants.any? ? 1 : 0
   ].sum
 
   status_options = [
@@ -89,11 +90,14 @@
         <%# Tenant Filter %>
         <% if tenant_filter_enabled? && available_tenants.any? %>
           <div class="md:w-auto">
-            <%= render "ruby_llm/agents/shared/select_dropdown",
-                name: "tenant_id",
-                filter_id: "tenant_id",
-                options: [{ value: "", label: "All Tenants" }] + available_tenants.map { |t| { value: t, label: t.truncate(15) } },
-                selected: params[:tenant_id],
+            <%= render "ruby_llm/agents/shared/filter_dropdown",
+                name: "tenant_ids[]",
+                filter_id: "tenant_ids",
+                label: "Tenants",
+                all_label: "All Tenants",
+                options: available_tenants,
+                selected: selected_tenants,
+                searchable: true,
                 icon: "M19 21V5a2 2 0 00-2-2H7a2 2 0 00-2 2v16m14 0h2m-2 0h-5m-9 0H3m2 0h5M9 7h1m-1 4h1m4-4h1m-1 4h1m-5 10v-5a1 1 0 011-1h2a1 1 0 011 1v5m-4 0h4",
                 width: "w-40",
                 full_width: true %>
@@ -173,7 +177,7 @@
               <span class="md:hidden">Clear</span>
             <% end %>
           <% end %>
-          <%= link_to ruby_llm_agents.export_executions_path(agent_types: selected_agents.presence, statuses: selected_statuses.presence, days: params[:days].presence, model_ids: selected_models.presence, tenant_id: params[:tenant_id].presence),
+          <%= link_to ruby_llm_agents.export_executions_path(agent_types: selected_agents.presence, statuses: selected_statuses.presence, days: params[:days].presence, model_ids: selected_models.presence, tenant_ids: selected_tenants.presence),
               class: "flex-1 md:flex-initial flex items-center justify-center gap-2 px-3 py-2 md:p-2 text-sm md:text-base text-gray-600 md:text-gray-400 dark:text-gray-300 md:dark:text-gray-400 bg-gray-50 md:bg-transparent dark:bg-gray-700 md:dark:bg-transparent hover:text-gray-600 md:hover:text-gray-600 dark:hover:text-gray-200 hover:bg-gray-100 dark:hover:bg-gray-600 md:dark:hover:bg-gray-700 rounded-lg transition-colors",
               title: "Export CSV" do %>
             <svg class="w-4 h-4" fill="none" stroke="currentColor" viewBox="0 0 24 24">

data/app/views/ruby_llm/agents/executions/show.html.erb

@@ -57,6 +57,16 @@
   </div>
 <% end %>
 
+<!-- Soft-purge banner -->
+<% if @execution.soft_purged? %>
+  <div class="flex items-start gap-2 bg-amber-50 dark:bg-amber-900/20 border border-amber-200 dark:border-amber-800 rounded px-3 py-2 mb-2">
+    <span class="text-amber-600 dark:text-amber-400 text-xs font-mono leading-5">
+      &#9888; Execution details were purged<% if @execution.soft_purged_at %> on <%= @execution.soft_purged_at.strftime("%b %d, %Y") %><% end %>.
+      Cost, token, and timing analytics are preserved.
+    </span>
+  </div>
+<% end %>
+
 <!-- Stats inline row -->
 <div class="flex flex-wrap items-center gap-x-4 gap-y-1 font-mono text-xs text-gray-400 dark:text-gray-500 mb-2">
   <span><span class="text-gray-800 dark:text-gray-200"><%= number_to_human_short(@execution.duration_ms || 0) %>ms</span> duration</span>
@@ -70,8 +80,8 @@
 <!-- ── audio player ──────────────────── -->
 <% if @execution.agent_type.to_s.match?(/Speaker|Narrator|Transcriber/i) ||
       @execution.metadata&.dig("audio_duration_seconds").present? ||
-      @execution.response&.dig("audio_data_uri").present? ||
-      @execution.response&.dig("audio_url").present? %>
+      @execution.response_hash["audio_data_uri"].present? ||
+      @execution.response_hash["audio_url"].present? %>
   <%= render "ruby_llm/agents/executions/audio_player" %>
 <% end %>
 
@@ -254,16 +264,18 @@
 <% end %>
 
 <!-- ── parameters ──────────────────── -->
-<div class="flex items-center gap-3 mt-6 mb-3">
-  <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">parameters</span>
-  <div class="flex-1 border-t border-gray-200 dark:border-gray-800"></div>
-  <button
-    type="button"
-    data-copy-json="<%= Base64.strict_encode64(JSON.pretty_generate(@execution.parameters || {})) %>"
-    class="copy-json-btn font-mono text-xs text-gray-400 dark:text-gray-500 hover:text-gray-700 dark:hover:text-gray-300"
-  >copy</button>
-</div>
-<pre class="bg-gray-50 dark:bg-gray-900 text-gray-900 dark:text-gray-100 rounded p-4 text-xs overflow-x-auto font-mono"><%= highlight_json(@execution.parameters || {}) %></pre>
+<% if @execution.detail && @execution.parameters.present? %>
+  <div class="flex items-center gap-3 mt-6 mb-3">
+    <span class="text-[10px] font-medium text-gray-400 dark:text-gray-600 uppercase tracking-widest font-mono">parameters</span>
+    <div class="flex-1 border-t border-gray-200 dark:border-gray-800"></div>
+    <button
+      type="button"
+      data-copy-json="<%= Base64.strict_encode64(JSON.pretty_generate(@execution.parameters)) %>"
+      class="copy-json-btn font-mono text-xs text-gray-400 dark:text-gray-500 hover:text-gray-700 dark:hover:text-gray-300"
+    >copy</button>
+  </div>
+  <pre class="bg-gray-50 dark:bg-gray-900 text-gray-900 dark:text-gray-100 rounded p-4 text-xs overflow-x-auto font-mono"><%= highlight_json(@execution.parameters) %></pre>
+<% end %>
 
 <!-- ── response ──────────────────────── -->
 <% if @execution.response.present? %>
@@ -280,6 +292,7 @@
 <% end %>
 
 <!-- ── tool calls ──────────────────── -->
+<% if @execution.detail %>
 <% tool_calls = @execution.tool_calls || [] %>
 <% tool_call_count = tool_calls.size %>
 <div x-data="{ expanded: <%= tool_call_count <= 3 && tool_call_count > 0 %> }">
@@ -374,6 +387,7 @@
     <p class="text-xs text-gray-400 dark:text-gray-600 font-mono italic">no tool calls</p>
   <% end %>
 </div>
+<% end %>
 
 <!-- ── metadata ──────────────────────── -->
 <% if @execution.metadata.present? && @execution.metadata.any? %>

data/app/views/ruby_llm/agents/shared/_filter_dropdown.html.erb

@@ -10,11 +10,13 @@
   #       { value: "success", label: "Success", color: "bg-green-500" },
   #       { value: "error", label: "Error", color: "bg-red-500" }
   #     ],
-  #     selected: ["success"]
+  #     selected: ["success"],
+  #     searchable: true # renders a client-side search input above the options
 
   selected = local_assigns[:selected] || []
   show_all = local_assigns.fetch(:show_all_option, true)
   all_label = local_assigns[:all_label] || "All"
+  searchable = local_assigns.fetch(:searchable, false)
 
   current_label = if selected.empty?
     label
@@ -32,8 +34,31 @@
 
   has_selection = selected.any?
 %>
-<div class="relative" x-data="{ open: false }" @click.outside="open = false" data-filter="<%= filter_id %>">
-  <button type="button" @click="open = !open"
+<%#
+  Multi-select behavior:
+  - Checkbox click: toggle that option, mark dirty, keep dropdown open.
+  - Label click: clear other selections, check only this one, close, submit.
+  - Close dropdown (outside click, button toggle, Escape): if dirty, submit.
+  This batches checkbox picks into a single request when the user closes
+  the dropdown — no reliance on persisting open state across reload.
+%>
+<div class="relative"
+     x-data="{
+       open: false,
+       query: '',
+       dirty: false,
+       closeAndApply() {
+         this.open = false;
+         if (this.dirty) {
+           this.dirty = false;
+           this.$el.closest('form').requestSubmit();
+         }
+       }
+     }"
+     @click.outside="closeAndApply()"
+     @keydown.escape.window="if (open) closeAndApply()"
+     data-filter="<%= filter_id %>">
+  <button type="button" @click="open ? closeAndApply() : open = true"
     class="flex items-center gap-1.5 px-2 py-1 font-mono text-xs rounded
            hover:bg-gray-100 dark:hover:bg-gray-800/50 transition-colors
            <%= has_selection ? 'text-gray-900 dark:text-gray-100' : 'text-gray-400 dark:text-gray-500' %>">
@@ -50,7 +75,19 @@
        x-transition:enter-start="opacity-0 scale-95" x-transition:enter-end="opacity-100 scale-100"
        x-transition:leave="transition ease-in duration-75"
        x-transition:leave-start="opacity-100 scale-100" x-transition:leave-end="opacity-0 scale-95"
-       class="absolute z-20 mt-1 min-w-max bg-white dark:bg-gray-800 rounded-lg shadow-lg border border-gray-200 dark:border-gray-700 py-1 max-h-64 overflow-y-auto">
+       class="absolute z-20 mt-1 min-w-max w-56 bg-white dark:bg-gray-800 rounded-lg shadow-lg border border-gray-200 dark:border-gray-700 py-1">
+
+    <% if searchable %>
+      <div class="px-2 py-1.5 border-b border-gray-100 dark:border-gray-700 sticky top-0 bg-white dark:bg-gray-800">
+        <input type="text" x-model="query" @click.stop
+               placeholder="Search…"
+               x-ref="<%= filter_id %>_search"
+               x-effect="if (open) $nextTick(() => $refs['<%= filter_id %>_search']?.focus())"
+               class="w-full px-2 py-1 text-xs font-mono rounded border border-gray-200 dark:border-gray-700 bg-transparent text-gray-900 dark:text-gray-100 focus:outline-none focus:ring-1 focus:ring-blue-500 focus:border-blue-500">
+      </div>
+    <% end %>
+
+    <div class="max-h-56 overflow-y-auto">
 
     <% if show_all %>
       <div class="px-3 py-1.5 border-b border-gray-100 dark:border-gray-700">
@@ -60,7 +97,7 @@
                  <%= selected.empty? ? 'checked' : '' %>
                  @change="
                    $el.closest('[data-filter]').querySelectorAll('.filter-cb').forEach(c => c.checked = false);
-                   $el.closest('form').requestSubmit();
+                   dirty = true;
                  ">
           <span class="text-gray-700 dark:text-gray-200"><%= all_label %></span>
         </label>
@@ -68,13 +105,14 @@
     <% end %>
 
     <% options.each do |option| %>
-      <div class="flex items-center gap-2 px-3 py-1.5 font-mono text-xs text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700">
+      <div class="flex items-center gap-2 px-3 py-1.5 font-mono text-xs text-gray-700 dark:text-gray-200 hover:bg-gray-50 dark:hover:bg-gray-700"
+           <% if searchable %>x-show="query === '' || '<%= j(option[:label].to_s.downcase) %>'.includes(query.toLowerCase())"<% end %>>
         <input type="checkbox"
                name="<%= name %>"
                value="<%= option[:value] %>"
                class="filter-cb rounded border-gray-300 dark:border-gray-600 text-blue-600 focus:ring-blue-500 dark:bg-gray-700"
                <%= selected.include?(option[:value].to_s) ? 'checked' : '' %>
-               @change="$el.closest('form').requestSubmit()">
+               @change="dirty = true">
         <span class="flex-1 flex items-center gap-1.5 cursor-pointer"
               @click.prevent="
                 $el.closest('[data-filter]').querySelectorAll('.filter-cb').forEach(c => c.checked = false);
@@ -89,5 +127,6 @@
         </span>
       </div>
     <% end %>
+    </div>
   </div>
 </div>

data/app/views/ruby_llm/agents/shared/_tenant_filter.html.erb

@@ -6,8 +6,8 @@
               class="bg-transparent border border-gray-200 dark:border-gray-800 rounded px-2 py-0.5 text-xs font-mono text-gray-900 dark:text-gray-100 focus:ring-1 focus:ring-gray-400 dark:focus:ring-gray-600 focus:border-gray-400 dark:focus:border-gray-600">
         <option value="">all tenants</option>
         <% available_tenants.each do |tenant| %>
-          <option value="<%= tenant %>" <%= 'selected' if tenant == current_tenant_id %>>
-            <%= tenant %>
+          <option value="<%= tenant[:value] %>" <%= 'selected' if tenant[:value] == current_tenant_id %>>
+            <%= tenant[:label] %>
           </option>
         <% end %>
       </select>

data/app/views/ruby_llm/agents/system_config/show.html.erb

@@ -51,8 +51,12 @@
     <span class="badge badge-sm <%= @config.async_logging ? 'badge-success' : 'badge-timeout' %>"><%= @config.async_logging ? 'on' : 'off' %></span>
   </div>
   <div class="flex items-center gap-3 py-0.5">
-    <span class="w-36 flex-shrink-0 text-gray-500 dark:text-gray-400">retention</span>
-    <span class="text-gray-900 dark:text-gray-200"><%= @config.retention_period.inspect %></span>
+    <span class="w-36 flex-shrink-0 text-gray-500 dark:text-gray-400">soft purge after</span>
+    <span class="text-gray-900 dark:text-gray-200"><%= @config.soft_purge_after ? @config.soft_purge_after.inspect : "disabled" %></span>
+  </div>
+  <div class="flex items-center gap-3 py-0.5">
+    <span class="w-36 flex-shrink-0 text-gray-500 dark:text-gray-400">hard purge after</span>
+    <span class="text-gray-900 dark:text-gray-200"><%= @config.hard_purge_after ? @config.hard_purge_after.inspect : "disabled" %></span>
   </div>
   <div class="flex items-center gap-3 py-0.5">
     <span class="w-36 flex-shrink-0 text-gray-500 dark:text-gray-400">job retries</span>

data/lib/generators/ruby_llm_agents/templates/initializer.rb.tt

@@ -67,7 +67,33 @@ RubyLLM::Agents.configure do |config|
   # Number of retry attempts for the async logging job on failure
   # config.job_retry_attempts = 3
 
-  # Retention period for execution records (used by cleanup tasks)
+  # ============================================
+  # Data Retention
+  # ============================================
+  #
+  # Two-tier purge of execution records. Run the retention job on a schedule
+  # (e.g. daily via cron, sidekiq-cron, or the `whenever` gem):
+  #
+  #   RubyLLM::Agents::RetentionJob.perform_later
+  #   # or: rake ruby_llm_agents:purge
+  #
+  # Soft purge: deletes prompts, responses, tool calls, attempts, and other
+  # large payloads in execution_details and tool_executions. The executions
+  # row is preserved so cost, token, and latency analytics stay intact. A
+  # truncated copy of error_message is kept in executions.metadata.
+  #
+  # Hard purge: deletes the executions row entirely (cascades remove any
+  # remaining dependents). Use a longer window — this removes the execution
+  # from analytics.
+  #
+  # Set either to nil to disable that tier. soft_purge_after must be less
+  # than hard_purge_after when both are set.
+  #
+  # config.soft_purge_after = 30.days
+  # config.hard_purge_after = 365.days
+
+  # Deprecated: retention_period is an alias for hard_purge_after. Prefer the
+  # two-tier settings above.
   # config.retention_period = 30.days
 
   # ============================================

data/lib/ruby_llm/agents/core/configuration.rb

@@ -50,9 +50,26 @@ module RubyLLM
       #   When false, executions are logged synchronously.
       #   @return [Boolean] Enable async logging (default: true)
 
+      # @!attribute [rw] soft_purge_after
+      #   How long to keep full execution details (prompts, responses, tool calls,
+      #   attempts) before the retention job destroys them. The executions row is
+      #   preserved so cost, token, and latency analytics remain intact. A
+      #   truncated copy of the error message is stamped into metadata for
+      #   long-term error-rate trend analysis.
+      #   Set to nil to disable soft purging.
+      #   @return [ActiveSupport::Duration, nil] Soft-purge window (default: 30.days)
+
+      # @!attribute [rw] hard_purge_after
+      #   How long to keep the executions row itself before the retention job
+      #   destroys it entirely. Must be greater than soft_purge_after when both
+      #   are set. Set to nil to retain executions indefinitely.
+      #   @return [ActiveSupport::Duration, nil] Hard-purge window (default: 365.days)
+
       # @!attribute [rw] retention_period
-      #   How long to retain execution records before cleanup.
-      #   @return [ActiveSupport::Duration] Retention period (default: 30.days)
+      #   Deprecated. Alias for hard_purge_after, kept for backward compatibility.
+      #   Prefer configuring soft_purge_after and hard_purge_after explicitly.
+      #   @return [ActiveSupport::Duration, nil] Hard-purge window
+      #   @deprecated Use {#hard_purge_after} instead.
 
       # @!attribute [rw] anomaly_cost_threshold
       #   Cost threshold in dollars that triggers anomaly logging.
@@ -379,7 +396,6 @@ module RubyLLM
       # Attributes without validation (simple accessors)
       attr_accessor :default_model,
         :async_logging,
-        :retention_period,
         :dashboard_parent_controller,
         :basic_auth_username,
         :basic_auth_password,
@@ -464,7 +480,9 @@ module RubyLLM
         :tenant_resolver,
         :tenant_config_resolver,
         :default_retries,
-        :budgets
+        :budgets,
+        :soft_purge_after,
+        :hard_purge_after
 
       attr_writer :cache_store
 
@@ -594,6 +612,44 @@ module RubyLLM
         @default_embedding_batch_size = value
       end
 
+      # Sets soft_purge_after with validation
+      #
+      # @param value [ActiveSupport::Duration, Numeric, nil] Window or nil to disable
+      # @raise [ArgumentError] If value is not a Duration/Numeric or nil, or is negative
+      def soft_purge_after=(value)
+        validate_purge_window!(:soft_purge_after, value)
+        @soft_purge_after = value
+        validate_purge_ordering!
+      end
+
+      # Sets hard_purge_after with validation
+      #
+      # @param value [ActiveSupport::Duration, Numeric, nil] Window or nil to disable
+      # @raise [ArgumentError] If value is not a Duration/Numeric or nil, or is negative
+      def hard_purge_after=(value)
+        validate_purge_window!(:hard_purge_after, value)
+        @hard_purge_after = value
+        validate_purge_ordering!
+      end
+
+      # Deprecated alias for hard_purge_after.
+      #
+      # @return [ActiveSupport::Duration, nil]
+      # @deprecated Use {#hard_purge_after} instead.
+      def retention_period
+        hard_purge_after
+      end
+
+      # Deprecated setter for retention_period (maps to hard_purge_after).
+      #
+      # @param value [ActiveSupport::Duration, Numeric, nil]
+      # @deprecated Use {#hard_purge_after=} instead.
+      def retention_period=(value)
+        warn "[DEPRECATION] RubyLLM::Agents config.retention_period is deprecated. " \
+          "Use config.hard_purge_after instead (and set config.soft_purge_after for two-tier retention)."
+        self.hard_purge_after = value
+      end
+
       # Sets default_embedding_dimensions with validation
       #
       # @param value [Integer, nil] Dimensions (must be nil or > 0)
@@ -616,7 +672,8 @@ module RubyLLM
         @default_timeout = 60
         @cache_store = nil
         @async_logging = true
-        @retention_period = 30.days
+        @soft_purge_after = 30.days
+        @hard_purge_after = 365.days
         @anomaly_cost_threshold = 5.00
         @anomaly_duration_threshold = 10_000
         @dashboard_auth = ->(_controller) { true }
@@ -960,7 +1017,8 @@ module RubyLLM
           },
           logging: {
             async_logging: async_logging,
-            retention_period: retention_period,
+            soft_purge_after: soft_purge_after,
+            hard_purge_after: hard_purge_after,
             job_retry_attempts: job_retry_attempts,
             track_executions: track_executions,
             track_cache_hits: track_cache_hits,
@@ -1161,6 +1219,30 @@ module RubyLLM
           raise ArgumentError, "budgets[:enforcement] must be :none, :soft, or :hard"
         end
       end
+
+      # Validates a purge-window value (Duration, Numeric seconds, or nil).
+      #
+      # @param attr [Symbol] Attribute name for error messages
+      # @param value [ActiveSupport::Duration, Numeric, nil] Value to validate
+      # @raise [ArgumentError] If value is neither nil nor a non-negative duration/number
+      def validate_purge_window!(attr, value)
+        return if value.nil?
+        return if value.is_a?(ActiveSupport::Duration) && value.to_i >= 0
+        return if value.is_a?(Numeric) && value >= 0
+
+        raise ArgumentError, "#{attr} must be an ActiveSupport::Duration, non-negative Numeric, or nil"
+      end
+
+      # Ensures soft_purge_after is strictly less than hard_purge_after when both are set.
+      #
+      # @raise [ArgumentError] If ordering is violated
+      def validate_purge_ordering!
+        return if @soft_purge_after.nil? || @hard_purge_after.nil?
+        return if @soft_purge_after.to_i < @hard_purge_after.to_i
+
+        raise ArgumentError, "soft_purge_after (#{@soft_purge_after.inspect}) must be less than " \
+          "hard_purge_after (#{@hard_purge_after.inspect})"
+      end
     end
   end
 end

data/lib/ruby_llm/agents/core/version.rb

@@ -4,6 +4,6 @@ module RubyLLM
   module Agents
     # Current version of the RubyLLM::Agents gem
     # @return [String] Semantic version string
-    VERSION = "3.12.0"
+    VERSION = "3.13.0"
   end
 end

data/lib/ruby_llm/agents/image/concerns/image_operation_execution.rb

@@ -95,12 +95,13 @@ module RubyLLM
         def record_failed_execution(error, started_at)
           return unless defined?(RubyLLM::Agents::Execution)
 
-          execution_data = build_failed_execution_data(error, started_at)
+          execution_data, detail_data = build_failed_execution_data(error, started_at)
 
           if config.async_logging && defined?(ExecutionLoggerJob)
-            ExecutionLoggerJob.perform_later(execution_data)
+            ExecutionLoggerJob.perform_later(execution_data.merge(_detail_data: detail_data))
           else
-            RubyLLM::Agents::Execution.create!(execution_data)
+            execution = RubyLLM::Agents::Execution.create!(execution_data)
+            execution.create_detail!(detail_data) if detail_data.present?
           end
         rescue => e
           Rails.logger.error("[RubyLLM::Agents] Failed to record failed #{execution_type} execution: #{e.message}") if defined?(Rails)
@@ -124,7 +125,7 @@ module RubyLLM
         end
 
         def build_failed_execution_data(error, started_at)
-          {
+          execution_data = {
             agent_type: self.class.name,
             tenant_id: @tenant_id,
             execution_type: execution_type,
@@ -137,9 +138,12 @@ module RubyLLM
             started_at: started_at,
             completed_at: Time.current,
             error_class: error.class.name,
-            error_message: error.message.truncate(1000),
             metadata: {}
           }
+
+          detail_data = {error_message: error.message.to_s.truncate(1000)}
+
+          [execution_data, detail_data]
         end
 
         def build_metadata(result)

data/lib/ruby_llm/agents/infrastructure/retention_job.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  module Agents
+    # Background job that enforces two-tier data retention on execution records.
+    #
+    # Soft pass: for executions older than {Configuration#soft_purge_after},
+    # destroys the associated execution_details and tool_executions rows,
+    # preserves a truncated copy of error_message in metadata, and stamps
+    # metadata["soft_purged_at"] so the dashboard can surface the state and
+    # the pass stays idempotent.
+    #
+    # Hard pass: for executions older than {Configuration#hard_purge_after},
+    # destroys the executions row itself. The foreign-key cascade removes
+    # any remaining details or tool_executions.
+    #
+    # Either tier may be set to nil in configuration to skip that pass.
+    #
+    # @example Enqueue manually
+    #   RubyLLM::Agents::RetentionJob.perform_later
+    #
+    # @example Schedule daily (whenever gem)
+    #   every 1.day, at: "3:00 am" do
+    #     runner "RubyLLM::Agents::RetentionJob.perform_later"
+    #   end
+    #
+    # @api public
+    class RetentionJob < ActiveJob::Base
+      queue_as :default
+
+      ERROR_MESSAGE_MAX_LENGTH = 500
+      BATCH_SIZE = 500
+
+      # Runs the soft and hard retention passes based on current configuration.
+      #
+      # @return [Hash] counts of rows affected in each pass
+      def perform
+        {
+          soft_purged: soft_purge,
+          hard_purged: hard_purge
+        }
+      end
+
+      private
+
+      # Destroys detail + tool_execution rows for executions older than the
+      # soft-purge window that have not already been soft-purged. Stamps
+      # metadata with the purge timestamp and preserves a truncated
+      # error_message for long-term error-rate analytics.
+      #
+      # The "already purged" filter runs in Ruby rather than SQL because
+      # JSON key-exists operators differ across SQLite/Postgres/MySQL; this
+      # keeps the job adapter-agnostic. We batch to bound memory.
+      def soft_purge
+        window = RubyLLM::Agents.configuration.soft_purge_after
+        return 0 if window.nil?
+
+        cutoff = window.ago
+        count = 0
+
+        Execution
+          .where("created_at < ?", cutoff)
+          .includes(:detail)
+          .find_in_batches(batch_size: BATCH_SIZE) do |batch|
+            batch.each do |execution|
+              next if execution.soft_purged?
+
+              purge_one(execution)
+              count += 1
+            end
+          end
+
+        count
+      end
+
+      # Destroys executions (and everything cascaded from them) older than
+      # the hard-purge window.
+      def hard_purge
+        window = RubyLLM::Agents.configuration.hard_purge_after
+        return 0 if window.nil?
+
+        cutoff = window.ago
+        total = 0
+
+        Execution.where("created_at < ?", cutoff).in_batches(of: BATCH_SIZE) do |batch|
+          total += batch.destroy_all.size
+        end
+
+        total
+      end
+
+      # Performs the soft purge for a single execution.
+      def purge_one(execution)
+        preserved_error = preserved_error_message(execution)
+
+        Execution.transaction do
+          execution.detail&.destroy
+          execution.tool_executions.destroy_all
+
+          new_metadata = (execution.metadata || {}).merge(
+            "soft_purged_at" => Time.current.iso8601
+          )
+          new_metadata["error_message"] = preserved_error if preserved_error
+
+          execution.update_columns(metadata: new_metadata)
+        end
+      end
+
+      # Returns a truncated copy of the detail's error_message, or nil.
+      def preserved_error_message(execution)
+        raw = execution.detail&.error_message
+        return nil if raw.blank?
+
+        raw.to_s.truncate(ERROR_MESSAGE_MAX_LENGTH)
+      end
+    end
+  end
+end

data/lib/ruby_llm/agents/rails/engine.rb

@@ -33,6 +33,7 @@ module RubyLLM
       # @api private
       config.to_prepare do
         require_relative "../infrastructure/execution_logger_job"
+        require_relative "../infrastructure/retention_job"
         require_relative "../core/instrumentation"
         require_relative "../core/base"
 
@@ -153,18 +154,33 @@ module RubyLLM
           end
           helper_method :tenant_scoped_executions
 
-          # Returns list of available tenants for filtering dropdown
+          # Returns the list of tenants for the dropdown as label/value pairs.
           #
-          # @return [Array<String>] Unique tenant IDs from executions
+          # Tenants that have a matching row in ruby_llm_agents_tenants get their
+          # configured name; legacy or string-only tenants fall back to the raw
+          # tenant_id so nothing disappears from the filter.
+          #
+          # Two queries total — one DISTINCT pluck on executions, one pluck on
+          # tenants — regardless of how many tenant_ids exist.
+          #
+          # @return [Array<Hash>] Entries shaped as { value:, label: }
           # @api public
           def available_tenants
             return @available_tenants if defined?(@available_tenants)
 
-            @available_tenants = RubyLLM::Agents::Execution
+            tenant_ids = RubyLLM::Agents::Execution
               .where.not(tenant_id: nil)
               .distinct
               .pluck(:tenant_id)
-              .sort
+
+            names_by_id = RubyLLM::Agents::Tenant
+              .where(tenant_id: tenant_ids)
+              .pluck(:tenant_id, :name)
+              .to_h
+
+            @available_tenants = tenant_ids
+              .map { |id| {value: id, label: (names_by_id[id].presence || id).to_s} }
+              .sort_by { |t| t[:label].downcase }
           end
           helper_method :available_tenants
         end)

data/lib/ruby_llm/agents/routing.rb

@@ -115,6 +115,15 @@ module RubyLLM
         @ask_message || options[:message] || super
       end
 
+      # Override call to capture the caller's stream block so it can be
+      # forwarded to the delegated agent. Without this, chunks from the
+      # delegated agent are swallowed because build_result has no access
+      # to the original block.
+      def call(&block)
+        @delegation_stream_block = block
+        super
+      end
+
       # Override process_response to parse the route from LLM output.
       def process_response(response)
         raw = response.content.to_s.strip.downcase.gsub(/[^a-z0-9_]/, "")
@@ -131,25 +140,39 @@ module RubyLLM
       end
 
       # Override build_result to return a RoutingResult.
-      # Auto-delegates to the mapped agent when the route has an `agent:` mapping.
+      # Auto-delegates to the mapped agent when the route has an `agent:` mapping,
+      # unless the caller opts out with `auto_delegate: false`.
       def build_result(content, response, context)
         base = super
 
-        # Auto-delegate to the mapped agent
         agent_class = content[:agent_class]
-        if agent_class
-          content[:delegated_result] = agent_class.call(**delegation_params)
+        if agent_class && auto_delegate?
+          content[:delegated_result] = if @delegation_stream_block
+            agent_class.call(**delegation_params, &@delegation_stream_block)
+          else
+            agent_class.call(**delegation_params)
+          end
         end
 
         RoutingResult.new(base_result: base, route_data: content)
       end
 
+      # Whether auto-delegation to the mapped agent is enabled for this call.
+      # Defaults to true. Pass `auto_delegate: false` to receive a
+      # classification-only RoutingResult with `delegated? == false` and
+      # `agent_class` set so the caller can invoke it manually.
+      #
+      # @return [Boolean]
+      def auto_delegate?
+        @options.fetch(:auto_delegate, true)
+      end
+
       # Builds params to forward to the delegated agent.
       # Forwards original message and custom params, excludes routing internals.
       #
       # @return [Hash] Params for the delegated agent
       def delegation_params
-        forward = @options.except(:dry_run, :skip_cache, :debug, :stream_events)
+        forward = @options.except(:dry_run, :skip_cache, :debug, :stream_events, :auto_delegate)
         forward[:_parent_execution_id] = @parent_execution_id if @parent_execution_id
         forward[:_root_execution_id] = @root_execution_id if @root_execution_id
         forward

data/lib/ruby_llm/agents.rb

@@ -96,6 +96,7 @@ if defined?(Rails)
   require_relative "agents/core/inflections"
   require_relative "agents/core/instrumentation"
   require_relative "agents/infrastructure/execution_logger_job"
+  require_relative "agents/infrastructure/retention_job"
 end
 require_relative "agents/rails/engine" if defined?(Rails::Engine)
 

data/lib/tasks/ruby_llm_agents.rake

@@ -7,6 +7,13 @@ namespace :ruby_llm_agents do
     RubyLlmAgents::DoctorGenerator.start([])
   end
 
+  desc "Run the retention job synchronously (soft + hard purges per configuration)"
+  task purge: :environment do
+    result = RubyLLM::Agents::RetentionJob.new.perform
+    puts "Soft purged: #{result[:soft_purged]} executions (details destroyed)"
+    puts "Hard purged: #{result[:hard_purged]} executions (rows destroyed)"
+  end
+
   desc "Rename an agent type in execution records. Usage: rake ruby_llm_agents:rename_agent FROM=OldName TO=NewName [DRY_RUN=1]"
   task rename_agent: :environment do
     from = ENV["FROM"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby_llm-agents
 version: !ruby/object:Gem::Version
-  version: 3.12.0
+  version: 3.13.0
 platform: ruby
 authors:
 - adham90
@@ -29,14 +29,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.12.0
+        version: 1.14.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.12.0
+        version: 1.14.1
 - !ruby/object:Gem::Dependency
   name: csv
   requirement: !ruby/object:Gem::Requirement
@@ -290,6 +290,7 @@ files:
 - lib/ruby_llm/agents/infrastructure/circuit_breaker.rb
 - lib/ruby_llm/agents/infrastructure/execution_logger_job.rb
 - lib/ruby_llm/agents/infrastructure/reliability.rb
+- lib/ruby_llm/agents/infrastructure/retention_job.rb
 - lib/ruby_llm/agents/pipeline.rb
 - lib/ruby_llm/agents/pipeline/builder.rb
 - lib/ruby_llm/agents/pipeline/context.rb