insika 0.7.0 → 0.8.0

data/lib/insika/session_store.rb

@@ -23,11 +23,11 @@ module Insika
     KEY_PREFIX = "session:"
 
     Session = Data.define(:id, :messages, :vars, :memory_refs,
-                          :created_at, :updated_at, :briefing, :evidence) do
+                          :created_at, :updated_at, :briefing, :evidence, :compaction) do
       # Trailing members with defaults: an old record without the "briefing" /
-      # "evidence" keys reads as empty/nil without a migration.
+      # "evidence" / "compaction" keys reads as empty/nil without a migration.
       def initialize(id:, messages:, vars:, memory_refs:, created_at:, updated_at:,
-                     briefing: nil, evidence: nil)
+                     briefing: nil, evidence: nil, compaction: nil)
         super
       end
     end
@@ -150,6 +150,35 @@ module Insika
       to_session(record)
     end
 
+    # -> Session. Persists the in-session compaction state (RFC-0044): the
+    # summary of messages[0...upto] plus the boundary. `upto` is MONOTONIC —
+    # a write that does not move the boundary forward is a no-op (a stale
+    # double-write from a racing worker can never move it backwards). `runs`
+    # counts compactions over the session's lifetime (the trace reports it).
+    #
+    # CONCURRENCY NOTE: an unlocked RMW (read -> mutate -> set), like
+    # update_briefing — and safe for the same reason: nothing in the
+    # read/mutate/set path suspends, so no other writer can interleave
+    # mid-RMW. The LLM call that produced the summary happened BEFORE this
+    # method; only the plain write lives here.
+    def set_compaction(id, summary:, upto:, model: nil)
+      record = fetch!(id)
+      current = record["compaction"]
+      upto = Integer(upto)
+      return to_session(record) if current && upto <= current["upto"].to_i
+
+      record["compaction"] = {
+        "summary" => Coercion.utf8(summary.to_s),
+        "upto" => upto,
+        "runs" => (current ? current["runs"].to_i : 0) + 1,
+        "model" => Coercion.presence(model.to_s),
+        "at" => timestamp
+      }.compact
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_session(record)
+    end
+
     # -> bool (delegates to the backend: false for a nonexistent id)
     def delete(id)
       @store.delete(SCOPE, key_for(id))
@@ -189,7 +218,8 @@ module Insika
         created_at: record["created_at"],
         updated_at: record["updated_at"],
         briefing: record["briefing"] || { "fields" => {}, "next_step" => nil },
-        evidence: record["evidence"]
+        evidence: record["evidence"],
+        compaction: record["compaction"]
       )
     end
 

data/lib/insika/settings_store.rb

@@ -30,7 +30,14 @@ module Insika
       "max_retries" => 2,
       "turn_timeout" => 120,
       "tool_timeout" => 30,
-      "compaction" => { "enabled" => false, "keep_last" => 20 },
+      # In-session compaction (RFC-0044): when a session's UNCOMPACTED
+      # transcript grows past `compact_after` messages, everything but the
+      # last `keep_last` is summarized (model -> compaction.model, else the
+      # platform utility_model) into one history fragment. `prompt` replaces
+      # the engine default wholesale (the distill convention). enabled: false
+      # = parity (nothing runs). Additive keys — reads overlay DEFAULTS.
+      "compaction" => { "enabled" => false, "keep_last" => 20,
+                        "compact_after" => 40, "model" => nil },
       # Data lifecycle (WS8, phase 2): the RETENTION window in days. The
       # tick's Retention sweep purges sessions (+traces), terminal tasks
       # (+checkpoints), memory cells and outcomes older than this. nil/0 =

data/lib/insika/soak/runner.rb

@@ -50,7 +50,7 @@ module Insika
 
         Environment:
           INSIKA_URL              base URL of the engine (default: http://localhost:9292)
-          OPENCLAW_GATEWAY_TOKEN  Bearer; falls back to ADMIN_TOKEN, then "local-demo"
+          INSIKA_GATEWAY_TOKEN  Bearer; falls back to ADMIN_TOKEN, then "local-demo"
       TXT
 
       # Poisson inter-arrival seconds: `-mean * Math.log(1.0 - rand)`. Seeded,
@@ -245,7 +245,7 @@ module Insika
           "  agent:    #{@agent}",
           "  shape:    #{@envelope[:turns_per_hour]} turns/h poisson, #{@envelope[:session_turns]}-turn sessions, " \
           "cap #{@envelope[:concurrency_cap]}, #{@envelope[:duration_hours]}h (#{@envelope[:warmup_hours]}h warmup)",
-          "  sample:   POST #{URI.join(target_url + '/', 'v1/responses')} model=openclaw:#{@agent} user=soak-1",
+          "  sample:   POST #{URI.join(target_url + '/', 'v1/responses')} model=insika:#{@agent} user=soak-1",
           "  out:      #{@out}/"
         ]
         unless @envelope.calibrated?
@@ -345,7 +345,7 @@ module Insika
 
       private
 
-      def resolve_token(env) = env["OPENCLAW_GATEWAY_TOKEN"] || env["ADMIN_TOKEN"] || "local-demo"
+      def resolve_token(env) = env["INSIKA_GATEWAY_TOKEN"] || env["ADMIN_TOKEN"] || "local-demo"
 
       def install_traps
         %w[INT TERM].each { |sig| Signal.trap(sig) { @stop_reason = "interrupted" } }
@@ -489,7 +489,7 @@ module Insika
           req["Authorization"] = "Bearer #{@token}"
           req["Content-Type"] = "application/json"
           req["Accept"] = "text/event-stream"
-          req.body = JSON.generate(model: "openclaw:#{agent}", user: user, stream: true, input: message)
+          req.body = JSON.generate(model: "insika:#{agent}", user: user, stream: true, input: message)
 
           t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           ttfb = nil

data/lib/insika/studio/app.rb

@@ -2078,7 +2078,14 @@ end
         "providers" => insika[:llm_provider_store] ? insika[:llm_provider_store].all.size : 0,
         "MCP servers" => insika[:mcp_store] ? insika[:mcp_store].all.size : 0
       }
-      now = Time.now
+      # UTC, deliberately: sessions stamp `updated_at` with `Time.now.utc.iso8601`,
+      # and every bucket below is keyed by a calendar part (date, hour) of that
+      # stamp. A LOCAL `now` mixes two clocks — on a UTC-3 host, from 21:00 local
+      # onward "today" is already tomorrow in UTC, so the day buckets stopped
+      # matching and the 24h floor was built three hours in the future, silently
+      # emptying both charts. Instant comparisons (`cutoff`) never had the bug;
+      # calendar arithmetic did.
+      now = Time.now.utc
       cutoff = now - (5 * 60)
       @active_now = sessions.count { |s| (t = parse_time(s.updated_at)) && t >= cutoff }
       @recent = sessions.sort_by { |s| s.updated_at.to_s }.reverse.first(8)
@@ -2089,8 +2096,11 @@ end
       # Trend affordances on the traffic stat cards: today vs yesterday from
       # the 14-day series (config counts — agents/skills/tools/providers —
       # have no daily shape and honestly show no trend).
-      today, yesterday = @activity.last(2).map(&:last)
-      @conv_trend = today - yesterday.to_i
+      # `@activity` is OLDEST FIRST and ends at today, so the last pair reads
+      # [yesterday, today]. Destructured the other way round it reported a
+      # first-conversation-of-the-day as "−1", every day.
+      yesterday, today = @activity.last(2).map(&:last)
+      @conv_trend = today.to_i - yesterday.to_i
       @msg_trend = message_delta(sessions, now)
       @persistence = insika.dig(:config, :persistence)
       view("home")
@@ -2113,11 +2123,14 @@ end
     end
 
     # [[Date, count], …] — one bucket per day over the window, most-recent last.
+    # `now` is UTC (render_home) and so is every `t` — see #utc_time. Both sides
+    # of the bucket key must be read off the same clock or the join silently
+    # misses.
     def activity_by_day(sessions, days:, now:)
       today = now.to_date
       buckets = Hash.new(0)
       sessions.each do |s|
-        t = parse_time(s.updated_at) or next
+        t = utc_time(s.updated_at) or next
         buckets[t.to_date] += 1
       end
       (0...days).to_a.reverse.map { |i| d = today - i; [d, buckets[d]] }
@@ -2131,7 +2144,7 @@ end
       floor = Time.utc(now.year, now.month, now.day, now.hour) - (hours - 1) * 3600
       buckets = Hash.new(0)
       sessions.each do |s|
-        t = parse_time(s.updated_at) or next
+        t = utc_time(s.updated_at) or next
         h = Time.utc(t.year, t.month, t.day, t.hour)
         buckets[h] += 1 if h >= floor
       end
@@ -2144,11 +2157,20 @@ end
     def message_delta(sessions, now)
       today = now.to_date
       sum = ->(date) do
-        sessions.sum { |s| (t = parse_time(s.updated_at)) && t.to_date == date ? Array(s.messages).size : 0 }
+        sessions.sum { |s| (t = utc_time(s.updated_at)) && t.to_date == date ? Array(s.messages).size : 0 }
       end
       sum.call(today) - sum.call(today - 1)
     end
 
+    # A stamp read for its CALENDAR parts, always in UTC. `Time.parse` honours
+    # whatever offset the string carries — ours are `Z`, but a record written by
+    # anything else would otherwise bucket by its own zone. `getutc`, not `utc`:
+    # the latter mutates the receiver.
+    def utc_time(value)
+      t = parse_time(value)
+      t&.getutc
+    end
+
     # --- History -------------------------------------------------------------
 
     # Recent conversations (all agents — the Session doesn't stamp the agent that

data/lib/insika/studio/forms.rb

@@ -461,6 +461,17 @@ module Studio
       # per-tenant map in the record — the view says so.
       v = presence(r.params["memory_ttl_days"])
       patch["memory_ttl_days"] = v.nil? ? nil : Integer(v)
+      # In-session compaction (RFC-0044). The checkbox is authoritative on
+      # this form (unchecked = disable); the numbers keep their stored value
+      # when cleared (deep_merge — the defaults backstop a fresh record);
+      # model blank = nil = the platform utility_model.
+      compaction = { "enabled" => r.params["compaction_enabled"] == "1",
+                     "model" => presence(r.params["compaction_model"]) }
+      %w[keep_last compact_after].each do |f|
+        v = presence(r.params["compaction_#{f}"])
+        compaction[f] = Integer(v) if v
+      end
+      patch["compaction"] = compaction
       patch
     end
 

data/lib/insika/studio/views/settings.erb

@@ -43,6 +43,17 @@
             <label>Memory TTL (days)<input type="text" name="memory_ttl_days" value="<%= @settings["memory_ttl_days"] %>" inputmode="numeric" placeholder="blank = off"></label>
           </div>
           <p class="muted">Memory TTL: how many days a customer memory cell lives before the daily sweep prunes it (per-fact <code>expires_at</code> overrides always win). Editing here sets the platform default for <strong>every</strong> cell; a per-tenant map authored in the settings record is replaced by this save.</p>
+          <hr>
+          <label class="check">
+            <input type="checkbox" name="compaction_enabled" value="1"<%== " checked" if @settings.dig("compaction", "enabled") %>>
+            in-session compaction — summarize old turns past the threshold
+          </label>
+          <div class="grid-2">
+            <label>keep_last <span class="muted">(messages kept verbatim)</span><input type="text" name="compaction_keep_last" value="<%= @settings.dig("compaction", "keep_last") %>" inputmode="numeric"></label>
+            <label>compact_after <span class="muted">(uncompacted messages that trigger it)</span><input type="text" name="compaction_compact_after" value="<%= @settings.dig("compaction", "compact_after") %>" inputmode="numeric"></label>
+          </div>
+          <label>compaction model <span class="muted">(blank = the platform utility_model)</span><input type="text" name="compaction_model" value="<%= @settings.dig("compaction", "model") %>" placeholder="deepseek-v4-flash"></label>
+          <p class="muted">When a session's uncompacted transcript grows past <code>compact_after</code> messages, everything but the last <code>keep_last</code> is summarized by the cheap model into one <code>&lt;conversation_summary&gt;</code> fragment; the tail stays verbatim and the boundary is stable (the prompt cache holds after it). Runs post-turn, off the critical path.</p>
         </form>
       </div>
 

data/lib/insika/telemetry/recorder.rb

@@ -40,7 +40,8 @@ module Insika
       # and units are part of the documented contract (docs/OBSERVABILITY.md) —
       # renaming one breaks every dashboard built on it.
       class Instruments
-        attr_reader :turns, :turn_duration, :tokens, :cost, :tool_calls, :tool_duration
+        attr_reader :turns, :turn_duration, :tokens, :cost, :tool_calls, :tool_duration,
+                    :cache_hit_rate, :loop_intervened, :context_compacted
 
         def initialize(meter)
           @turns = meter.create_counter("insika.turns", unit: "{turn}",
@@ -55,6 +56,12 @@ module Insika
                                                                   description: "Tool invocations")
           @tool_duration = meter.create_histogram("insika.tool.duration", unit: "s",
                                                                          description: "Wall time of a tool call")
+          @cache_hit_rate = meter.create_histogram("insika.cache.hit_rate", unit: "%",
+                                                                            description: "Prompt-cache hit rate of a turn (cached / billed prompt tokens)")
+          @loop_intervened = meter.create_counter("insika.tool.loop_intervened", unit: "{intervention}",
+                                                                                 description: "Loop-detector warnings delivered to the model")
+          @context_compacted = meter.create_counter("insika.context.compacted", unit: "{compaction}",
+                                                                                description: "In-session compactions persisted (RFC-0044)")
         end
       end
 
@@ -73,6 +80,8 @@ module Insika
         when :tool_call      then start_tool(meta, data)
         when :tool_result    then finish_tool(meta)
         when :data_tool_call then point_tool(meta, data)
+        when :tool_loop_intervened then count_loop(meta, data)
+        when :context_compacted then count_compaction(data)
         when :task_completed then finish_turn(meta, data, :ok)
         when :task_failed    then finish_turn(meta, data, :error)
         when :task_cancelled then finish_turn(meta, data, :cancelled)
@@ -166,6 +175,45 @@ module Insika
         @instruments.turns.add(1, attributes: labels)
         @instruments.turn_duration.record(seconds, attributes: labels) if seconds
         count_usage(turn, usage)
+        count_cache_hit(turn, usage)
+      end
+
+      # Same arithmetic as the Executor's per-agent series (stamp_cache_hit):
+      # the billed prompt is fresh input + cache reads + cache writes, and the
+      # hit rate is reads over the whole billed prompt — always in [0,100]. A
+      # turn with no billed prompt tokens (no usage, usage without the fields)
+      # records nothing: absence is not a 0% hit.
+      def count_cache_hit(turn, usage)
+        return unless usage
+
+        billed = usage[:input_tokens].to_i + usage[:cached_tokens].to_i +
+                 usage[:cache_creation_tokens].to_i
+        return unless billed.positive?
+
+        rate = (usage[:cached_tokens].to_i * 100.0) / billed
+        base = turn.labels.merge(attrs("insika.model" => usage[:model]&.to_s))
+        @instruments.cache_hit_rate.record(rate, attributes: base)
+      end
+
+      # The loop detector delivered its one-shot warning (`:tool_loop_intervened`,
+      # counts and the tool name, never arguments). An orphan event (no open turn)
+      # is ignored, like every other consumer of this stream.
+      def count_loop(meta, data)
+        return unless @instruments
+
+        turn = @turns[meta[:task_id]] or return
+        labels = turn.labels.merge(attrs("insika.tool" => data[:name]&.to_s))
+        @instruments.loop_intervened.add(1, attributes: labels)
+      end
+
+      # A compaction persisted (`:context_compacted`, RFC-0044) — counted by
+      # agent/model, INDEPENDENT of any open turn: it fires post-turn, usually
+      # after task_completed already closed the span.
+      def count_compaction(data)
+        return unless @instruments
+
+        labels = attrs("insika.agent" => data[:agent]&.to_s, "insika.model" => data[:model]&.to_s)
+        @instruments.context_compacted.add(1, attributes: labels)
       end
 
       # Tokens ride ONE counter split by `insika.token.type` (instead of four

data/lib/insika/templates/daily-digest/README.md

@@ -31,6 +31,15 @@ in the Playground — the artifact lands on the Artifacts tab either way.
 - The **numbers** are not. Swap the literal string in `agent.rb` for a
   `data_tool` against your own sales API and nothing else changes.
 
+## When the report needs real data
+
+One agent doing 30–50 tool calls at one reasoning effort is how a report turn
+hits the 300 s timeout. The recipe is to split the phases across agents —
+`thinking: "low"` miners fanned out with `spawn_subagents`, a `thinking: "high"`
+orchestrator that plans and writes. See
+[Artifacts](https://github.com/guizaols/insika/blob/main/docs/ARTIFACTS.md), "Reasoning effort on a report turn",
+and the `research-analyst` template for the fan-out shape.
+
 ## Edit it
 
 The skill's instructions are the actual report spec — change the palette,

data/lib/insika/templates/research-analyst/agent.rb

@@ -12,6 +12,12 @@
 # of a business idea, IN PARALLEL (each in its own isolated context), then
 # the lead synthesizes one recommendation.
 #
+# Reasoning effort is split by ROLE, not spread evenly: the specialists answer
+# one narrow question each (`thinking: "low"`), the lead plans the delegation
+# and weighs three answers against each other (`thinking: "high"`). A child
+# inherits the environment as a DEFAULT only, so its own `params` wins. See
+# docs/ARTIFACTS.md, "Reasoning effort on a report turn".
+#
 #   DEEPSEEK_API_KEY=sk-... ruby research-analyst/agent.rb "a subscription box for specialty coffee"
 #   DEEPSEEK_API_KEY=sk-... ruby research-analyst/agent.rb --serve
 require "insika"
@@ -21,19 +27,23 @@ team = Insika.system do
 
   agent("market") do
     model "deepseek-v4-flash"
+    params thinking: "low"
     instructions "Research the MARKET angle of a business idea: audience, demand, competitors. Three sentences."
   end
   agent("technical") do
     model "deepseek-v4-flash"
+    params thinking: "low"
     instructions "Research the TECHNICAL/OPERATIONAL angle of a business idea: what it takes to build and run it. Three sentences."
   end
   agent("risk") do
     model "deepseek-v4-flash"
+    params thinking: "low"
     instructions "Research the RISK angle of a business idea: what could make it fail. Three sentences."
   end
 
   agent "analyst" do
     model "deepseek-v4-flash"
+    params thinking: "high"
     instructions <<~PROMPT
       You are a research LEAD with no expertise of your own — never answer
       from your own knowledge. Given a business idea, call spawn_subagents

data/lib/insika/tool_batch.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Insika
+  # The batch arithmetic behind every mid-turn `user` append.
+  #
+  # A model step that calls tools produces ONE assistant message announcing N
+  # tool calls, followed by N `role: tool` messages. Anthropic rejects a `user`
+  # message that lands between two of those results outright, so the ONLY valid
+  # append point inside a turn is the instant the Nth result closes the batch.
+  # SteerInjector discovered this rule; LoopDetector and TurnBudget both live by
+  # it, which is why the counting lives here instead of twice.
+  #
+  # Not a general-purpose helper: it answers one question ("did a batch just
+  # close?") and remembers one fact ("was this batch halted"), because a
+  # `halt_when` batch has no next model step and anything appended there would
+  # sit unread forever.
+  class ToolBatch
+    def initialize
+      @expected = nil # tool calls announced by the batch in flight (nil = none)
+      @seen = 0
+      @halted = false
+    end
+
+    # Feeds a RubyLLM message (duck-typed). True EXACTLY on the message that
+    # closes a batch of tool calls — the append boundary. Everything else,
+    # including the assistant message that opens the batch, is false.
+    def closed?(message)
+      role = field(message, :role).to_s
+      return open(message) if role == "assistant"
+      return false unless role == "tool" && @expected
+
+      @seen += 1
+      return false if @seen < @expected
+
+      @expected = nil
+      true
+    end
+
+    # From after_tool_result, with the RAW result: a Tool::Halt is only
+    # recognizable there.
+    def halt!(result)
+      @halted = true if defined?(RubyLLM::Tool::Halt) && result.is_a?(RubyLLM::Tool::Halt)
+    end
+
+    def halted? = @halted
+
+    private
+
+    # An assistant message with no tool calls is the model TALKING: the turn is
+    # ending, so nothing is in flight any more.
+    def open(message)
+      calls = field(message, :tool_calls)
+      size = calls.respond_to?(:size) ? calls.size : 0
+      @expected = size.zero? ? nil : size
+      @seen = 0
+      @halted = false
+      false
+    end
+
+    def field(message, name)
+      return message.public_send(name) if message.respond_to?(name)
+      return message[name] || message[name.to_s] if message.respond_to?(:[])
+
+      nil
+    end
+  end
+end

data/lib/insika/tool_usage_report.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # The tool AUDIT the per-session trace cannot answer: `tool_traces` records
+  # every call, but one session at a time, and nothing aggregates — so "which
+  # tools does this agent carry and never use?" had no surface at all. This
+  # report is that surface. Read-only by design: it names the candidates, the
+  # OPERATOR removes (a tool the report flags may still be the one a rare but
+  # critical flow needs).
+  #
+  # Attribution rides the task record: a session does not stamp its agent, but
+  # every task carries the agent in its command payload — tasks → sessions →
+  # tool_traces is the same read the Studio does. Three findings per agent:
+  #
+  #   never_called — in `tools_allow`, zero calls in any stored trace. Dead
+  #                  weight: it costs schema tokens on every request and buys
+  #                  nothing (the pilot's `search_orders` is the known example).
+  #   error_rate   — called inside the window with > 30% conventional errors
+  #                  (the trace's own `ok` flag). Either the tool is broken or
+  #                  the model cannot hold its contract; both are operator work.
+  #   stale        — called at some point, but not once inside the window.
+  #
+  # Bounded and honest: it reads only what the stores kept (the trace caps at
+  # 200 entries/session), so a count here is "at least", never an exact total.
+  class ToolUsageReport
+    WINDOW_DAYS = 14
+    ERROR_RATE_THRESHOLD = 0.30
+
+    # One finding. kind: "never_called" | "error_rate" | "stale".
+    Row = Data.define(:agent, :tool, :kind, :detail) do
+      def to_h = { "agent" => agent, "tool" => tool, "kind" => kind, "detail" => detail }
+    end
+
+    Report = Data.define(:generated_at, :days, :agents, :rows) do
+      def to_h
+        { "generated_at" => generated_at, "days" => days, "agents" => agents,
+          "rows" => rows.map(&:to_h) }
+      end
+
+      # Human report, grouped by agent. Silent agents still print their header —
+      # "nothing flagged" is a result, not an omission.
+      def to_s
+        lines = ["tool usage — last #{days} day(s), generated #{generated_at}"]
+        agents.each do |agent|
+          mine = rows.select { |r| r.agent == agent }
+          lines << "" << "#{agent}: #{mine.empty? ? 'nothing flagged' : "#{mine.length} finding(s)"}"
+          mine.each { |r| lines << format("  %-13s %s — %s", r.kind, r.tool, r.detail) }
+        end
+        lines.join("\n")
+      end
+    end
+
+    def initialize(task_store:, tool_trace_store:, profile_source:, now: nil)
+      @task_store = task_store
+      @tool_trace_store = tool_trace_store
+      @profile_source = profile_source
+      @now = now
+    end
+
+    # -> Report. `agent:` narrows to one agent (must still be a stored profile).
+    def generate(days: WINDOW_DAYS, agent: nil)
+      now = @now || Time.now.utc
+      cutoff = now - (days * 24 * 60 * 60)
+      profiles = @profile_source.all_raw
+      profiles = profiles.select { |r| r["id"].to_s == agent.to_s } if agent
+      sessions = sessions_by_agent
+
+      rows = profiles.flat_map do |record|
+        id = record["id"].to_s
+        stats = tool_stats(sessions[id] || [], cutoff)
+        never_called_rows(id, record, stats) +
+          error_rate_rows(id, stats, days) +
+          stale_rows(id, stats)
+      end
+
+      Report.new(generated_at: now.iso8601, days: days,
+                 agents: profiles.map { |r| r["id"].to_s }.sort,
+                 rows: rows.sort_by { |r| [r.agent, r.kind, r.tool] }.freeze)
+    end
+
+    private
+
+    # agent id -> [session ids], via the task records (the only place a session
+    # is tied to its agent). A task without agent or session (operator commands,
+    # workflows without a chat) contributes nothing.
+    def sessions_by_agent
+      acc = Hash.new { |h, k| h[k] = [] }
+      @task_store.each_id do |task_id|
+        task = @task_store.find(task_id) or next
+        agent = task.command.is_a?(Hash) ? task.command.dig("payload", "agent") : nil
+        next if agent.to_s.empty? || task.session_id.to_s.empty?
+
+        acc[agent.to_s] << task.session_id
+      end
+      acc.transform_values(&:uniq)
+    end
+
+    # tool name -> { calls:, errors:, window_calls:, window_errors:, last_at: }
+    # over every stored trace entry of the agent's sessions.
+    def tool_stats(session_ids, cutoff)
+      stats = Hash.new { |h, k| h[k] = { calls: 0, errors: 0, window_calls: 0, window_errors: 0, last_at: nil } }
+      session_ids.each do |sid|
+        @tool_trace_store.for_session(sid).each do |entry|
+          s = stats[entry["tool"].to_s]
+          at = parse_time(entry["at"])
+          error = entry["ok"] == false
+          s[:calls] += 1
+          s[:errors] += 1 if error
+          s[:last_at] = at if at && (s[:last_at].nil? || at > s[:last_at])
+          next unless at && at >= cutoff
+
+          s[:window_calls] += 1
+          s[:window_errors] += 1 if error
+        end
+      end
+      stats
+    end
+
+    def never_called_rows(agent, record, stats)
+      allow = record["tools_allow"]
+      return [] if allow.nil? # no allowlist declared -> nothing to audit against
+
+      Array(allow).map(&:to_s).reject { |t| stats.key?(t) }.map do |tool|
+        Row.new(agent: agent, tool: tool, kind: "never_called",
+                detail: "in tools_allow, never called in any stored trace — " \
+                        "its schema still ships on every request")
+      end
+    end
+
+    def error_rate_rows(agent, stats, days)
+      stats.filter_map do |tool, s|
+        next if s[:window_calls].zero?
+
+        rate = s[:window_errors].to_f / s[:window_calls]
+        next if rate <= ERROR_RATE_THRESHOLD
+
+        Row.new(agent: agent, tool: tool, kind: "error_rate",
+                detail: "#{s[:window_errors]}/#{s[:window_calls]} call(s) errored in the last " \
+                        "#{days} day(s) (#{(rate * 100).round}%)")
+      end
+    end
+
+    def stale_rows(agent, stats)
+      stats.filter_map do |tool, s|
+        next if s[:window_calls].positive? || s[:last_at].nil?
+
+        Row.new(agent: agent, tool: tool, kind: "stale",
+                detail: "last called #{s[:last_at].iso8601}, not once inside the window")
+      end
+    end
+
+    def parse_time(value)
+      return nil if value.to_s.empty?
+
+      Time.parse(value.to_s).utc
+    rescue ArgumentError
+      nil
+    end
+  end
+end