insika 0.8.0 → 1.0.1

data/lib/insika/memory_trim.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Insika
+  # Hands freed memory back to the OS once a worker goes quiet. After a burst, glibc
+  # keeps what the turns freed inside its malloc arenas and the process stays at its
+  # peak until something calls malloc_trim — a full GC alone returns nothing. On a
+  # quiet pass (no turn in flight, enough allocated since the last trim) this runs a
+  # full GC and then malloc_trim(0).
+  #
+  # A no-op where malloc_trim does not exist (macOS, musl, a jemalloc LD_PRELOAD
+  # returns 0) or where `fiddle` is not in the bundle: it is not a gem dependency,
+  # the reference deployment adds it to its Gemfile.
+  class MemoryTrim
+    INTERVAL = 60 # seconds between checks
+    MIN_ALLOCATED = 1_000_000 # objects allocated since the last trim; less is not worth a full GC
+
+    def self.malloc_trim
+      require "fiddle"
+      fn = Fiddle::Function.new(Fiddle::Handle::DEFAULT["malloc_trim"], [Fiddle::TYPE_SIZE_T], Fiddle::TYPE_INT)
+      -> { fn.call(0) }
+    rescue LoadError, StandardError # no fiddle, or no malloc_trim symbol (Fiddle::DLError)
+      nil
+    end
+
+    def initialize(executor:, trim: self.class.malloc_trim, allocated: -> { GC.stat(:total_allocated_objects) })
+      @executor = executor
+      @trim = trim
+      @allocated = allocated
+      @last = @allocated.call
+    end
+
+    def enabled? = !@trim.nil?
+
+    # One check. -> true when it trimmed.
+    def run_once
+      return false unless @executor.in_flight.empty?
+      return false if @allocated.call - @last < MIN_ALLOCATED
+
+      GC.start
+      @trim.call
+      @last = @allocated.call
+      true
+    end
+
+    def start(parent:, interval: INTERVAL)
+      return false unless enabled?
+
+      parent.async do |t|
+        t.annotate("insika-memory-trim")
+        loop do
+          sleep(interval)
+          run_once
+        rescue StandardError => e
+          warn "[memory_trim] #{e.class}: #{e.message}"
+        end
+      end
+      true
+    end
+  end
+end

data/lib/insika/middleware.rb

@@ -35,11 +35,20 @@ module Insika
       self
     end
 
-    def call(state, &terminal)
-      chain = @middlewares.reverse.reduce(terminal) do |nxt, mw|
+    # Paid retrieval prepares context inside the leading edge limiter. Other
+    # middleware still receives the completed context and policy resolution.
+    def call(state, prepare: nil, &terminal)
+      edge = @middlewares.first if prepare && @middlewares.first.is_a?(EdgeLimiter)
+      links = edge ? @middlewares.drop(1) : @middlewares
+      chain = links.reverse.reduce(terminal) do |nxt, mw|
         proc { |s| mw.call(s, &nxt) }
       end
-      chain.call(state)
+      if edge
+        edge.call(state, prepare: prepare, &chain)
+      else
+        prepare&.call(state)
+        chain.call(state)
+      end
     end
   end
 end

data/lib/insika/model_metrics_store.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # Content-free request summaries; independent of the bounded diagnostic trace.
+  class ModelMetricsStore
+    SCOPE = "model_metrics"
+    # One row per completed turn (TurnTiming#metrics + agent/model/provider),
+    # keyed by task id; TaskStore#delete drops it with the task.
+    TURN_SCOPE = "turn_metrics"
+    # One row per closed UTC day the home charts: cost and requests, keyed "agent|YYYY-MM-DD"
+    # ("*" = every agent). See #home.
+    DAY_SCOPE = "model_metrics_day"
+    TURN_WINDOWS = %w[ttft_ms total_ms first_balloon_ms queue_ms prep_ms tools_ms].freeze
+    PERIODS = { "24h" => 86_400, "7d" => 7 * 86_400, "30d" => 30 * 86_400 }.freeze
+    VALUES = %w[cost input_tokens output_tokens cache_read_tokens cache_write_tokens thinking_tokens].freeze
+    FIELDS = %w[type request_id at operation agent provider model status duration_ms turn].freeze + VALUES
+
+    def initialize(store:)
+      @store = store
+    end
+
+    def self.task_prefix(task_id) = "#{task_id.to_s.bytesize}:#{task_id}:"
+
+    def record(task_id:, entry:) = record_many(task_id: task_id, entries: [entry])
+
+    # A turn's events in one transaction: each request's row is read and written
+    # once, however many events (request, usage, retries) it got.
+    def record_many(task_id:, entries:)
+      rows = entries.filter_map do |entry|
+        data = LLMTraceStore.sanitize(entry.slice(*FIELDS))
+        next unless %w[llm_request llm_usage].include?(data["type"])
+        next if data["request_id"].nil? || data["request_id"].empty?
+
+        data
+      end
+      return if rows.empty?
+
+      @store.transaction do
+        next unless @store.get(TaskStore::SCOPE, "#{TaskStore::KEY_PREFIX}#{task_id}")
+
+        rows.group_by { |data| data["request_id"] }.each do |request_id, events|
+          key = self.class.task_prefix(task_id) + request_id
+          row = @store.get(SCOPE, key) || {
+            "task_id" => task_id.to_s, "request_id" => request_id,
+            "attempts" => 0, "failed_attempts" => 0, "reported" => {}
+          }
+          events.each { |data| fold(row, data) }
+          @store.set(SCOPE, key, row)
+        end
+      end
+    rescue StandardError
+      nil
+    end
+
+    def record_turn(task_id:, row:)
+      @store.set(TURN_SCOPE, task_id.to_s, row)
+    rescue StandardError
+      nil
+    end
+
+    # One agent's (or everyone's) totals and turn summary for each fixed period,
+    # from a single read of the 30-day rows. -> { "24h" => { "totals", "turns" }, ... }
+    def windows(agent: nil, now: Time.now.utc)
+      from = now - PERIODS.values.max
+      rows = request_rows(from, now).select { |row| agent.nil? || row["agent"] == agent }
+      turns = turn_rows(from, now, agent: agent, provider: nil, model: nil)
+      PERIODS.to_h do |period, seconds|
+        cut = now - seconds
+        [period, { "totals" => summarize(rows.select { |row| Time.iso8601(row["completed_at"]) >= cut }),
+                   "turns" => turn_summary(turns.select { |row| Time.iso8601(row["at"]) >= cut }) }]
+      end
+    end
+
+    # Everything the Studio home shows: the last 24h (totals + turns), the cost
+    # of the 24h before, and one bucket per UTC day (oldest first, today last).
+    # Rows are read for the last 48h only. A day that ended before that never
+    # changes again, so its cost and request count are kept in DAY_SCOPE the first
+    # time a home needs it: 14 days of rows, scattered across a big file, cost
+    # seconds on a cold disk.
+    # ponytail: day rows are never pruned (one per day per agent); a task deleted
+    # later still counts in a kept day.
+    def home(agent: nil, now: Time.now.utc, days: 14)
+      today = Time.utc(now.year, now.month, now.day)
+      day_ago = now - 86_400
+      recent_from = day_ago - 86_400
+      day_starts = Array.new(days) { |i| today - (days - 1 - i) * 86_400 }
+      tag = "#{agent || '*'}|"
+      kept = @store.entries(DAY_SCOPE, tag).to_h { |key, value| [key.delete_prefix(tag), value] }
+      missing = day_starts.select { |day| day + 86_400 <= recent_from && !kept.key?(day.strftime("%F")) }
+      timed = request_rows([recent_from, *missing].min, now)
+        .select { |row| agent.nil? || row["agent"] == agent }
+        .map { |row| [row, Time.iso8601(row["completed_at"])] }
+      by_day = timed.group_by { |_, t| t.strftime("%F") }.transform_values { |pairs| pairs.map(&:first) }
+      day_total = ->(key) { summarize(by_day.fetch(key, [])).slice("cost", "requests") }
+      fresh = missing.to_h { |day| [day.strftime("%F"), day_total.(day.strftime("%F"))] }
+      keep_days(tag, fresh)
+      {
+        "totals" => summarize(timed.filter_map { |row, t| row if t >= day_ago }),
+        "turns" => turn_summary(turn_rows(day_ago, now, agent: agent, provider: nil, model: nil)),
+        "day_before_cost" => summarize(timed.filter_map { |row, t| row if t >= recent_from && t < day_ago })["cost"],
+        "daily" => day_starts.map do |day|
+          key = day.strftime("%F")
+          (kept[key] || fresh[key] || day_total.(key)).merge("at" => day.iso8601)
+        end
+      }
+    end
+
+    # `from`/`to` (Time) pick a custom range and win over `period`; the bucket size
+    # follows the span (see #bucket_count).
+    def report(period: "7d", agent: nil, provider: nil, model: nil, now: Time.now.utc, from: nil, to: nil)
+      if from && to
+        period, now = "custom", to
+      else
+        period = "7d" unless PERIODS.key?(period)
+        from = now - PERIODS.fetch(period)
+      end
+      rows = request_rows(from, now)
+      agents = rows.filter_map { |row| row["agent"] }.uniq.sort
+      providers = rows.filter_map { |row| row["provider"] }.uniq.sort
+      model_options = rows.filter_map { |row| row["model"] }.uniq.sort
+      rows.select! do |row|
+        (agent.nil? || row["agent"] == agent) &&
+          (provider.nil? || row["provider"] == provider) && (model.nil? || row["model"] == model)
+      end
+      {
+        "period" => period, "from" => from.utc.iso8601, "to" => now.utc.iso8601,
+        "step_seconds" => ((now - from) / bucket_count(period, now - from)).round,
+        "agents" => agents, "providers" => providers, "model_options" => model_options,
+        "totals" => summarize(rows),
+        "series" => time_series(rows, from: from, to: now, period: period),
+        "models" => rows.group_by { |row| [row["provider"], row["model"]] }
+          .sort_by { |key, _| key.map(&:to_s) }.map do |(name, model_name), group|
+            summarize(group).merge("provider" => name, "model" => model_name)
+          end,
+        # The same model serves the reply and the post-turn learning: this splits
+        # their cost ("chat" vs knowledge_*). Rows from before labeling read as "chat".
+        "operations" => rows.group_by { |row| row["operation"] || "chat" }.sort.map do |operation, group|
+          summarize(group).merge("operation" => operation)
+        end,
+        "turns" => turn_report(from, now, agent: agent, provider: provider, model: model),
+        "slowest" => rows.select { |row| row["duration_ms"] }.sort_by { |row| -row["duration_ms"] }
+          .first(20).map { |row| row.reject { |key, _| key == "reported" }.merge(summarize([row])) },
+        "history_note" => "History starts with deployment. Deleting a task removes its model history."
+      }
+    end
+
+    private
+
+    # a failed write only means the next home computes those days again
+    def keep_days(tag, days)
+      return if days.empty?
+
+      @store.transaction { days.each { |key, value| @store.set(DAY_SCOPE, "#{tag}#{key}", value) } }
+    rescue StandardError
+      nil
+    end
+
+    def request_rows(from, to) = rows_between(SCOPE, "completed_at", from, to)
+
+    RECENT_PAGE = 500
+    # A row is written when its turn ends (or flushes before waiting), so its
+    # write can trail its own timestamp by up to a turn. Paging stops only past
+    # this margin, so a late write is never cut off.
+    LATE_WRITE = 6 * 3600
+
+    # The rows whose `field` falls in [from, to], read newest-written first and
+    # stopping at the first page entirely older than `from` (minus LATE_WRITE):
+    # a window costs its own rows, not the whole history. The stop test reads the
+    # page's oldest RECENT_PAGE rows, so a doubled page stops as early as a small one.
+    # ponytail: offset paging over write order; a time-keyed index if windows reach far back.
+    def rows_between(scope, field, from, to)
+      floor = from - LATE_WRITE
+      rows = []
+      offset = 0
+      limit = RECENT_PAGE
+      loop do
+        page = @store.recent(scope, nil, limit, offset)
+        times = page.map { |_key, row| row.is_a?(Hash) && row[field] ? Time.iso8601(row[field]) : nil }
+        page.each_with_index { |(_key, row), i| rows << row if times[i] && times[i] >= from && times[i] <= to }
+        break if page.size < limit || times.last(RECENT_PAGE).all? { |t| t && t < floor }
+
+        offset += limit
+        limit *= 2 # each call orders the whole scope: few big pages, not many small ones
+      end
+      rows
+    end
+
+    def turn_report(from, to, agent:, provider:, model:)
+      turn_summary(turn_rows(from, to, agent: agent, provider: provider, model: model))
+    end
+
+    def turn_rows(from, to, agent:, provider:, model:)
+      rows_between(TURN_SCOPE, "at", from, to).select do |row|
+        (agent.nil? || row["agent"] == agent) &&
+          (provider.nil? || row["provider"] == provider) && (model.nil? || row["model"] == model)
+      end
+    end
+
+    # Turn latency (each window's p50/p95) and per-tool health over turn rows.
+    def turn_summary(turns)
+      windows = TURN_WINDOWS.to_h do |window|
+        values = turns.filter_map { |row| row[window] }.sort
+        [window, { "measured" => values.size, "p50" => percentile(values, 50), "p95" => percentile(values, 95) }]
+      end
+      tools = turns.flat_map { |row| Array(row["tools"]) }.group_by(&:first).sort.map do |name, calls|
+        ms = calls.filter_map { |call| call[2] }.sort
+        { "tool" => name, "calls" => calls.size, "failures" => calls.count { |call| call[1] == false },
+          "p50_ms" => percentile(ms, 50), "p95_ms" => percentile(ms, 95) }
+      end
+      failed = turns.select { |row| row["status"] == "failed" }
+      { "count" => turns.size, "failures" => failed.size,
+        "failure_stages" => failed.group_by { |row| row["stage"] || "unknown" }.transform_values(&:size).sort.to_h,
+        "windows" => windows, "tools" => tools }
+    end
+
+    # Nearest rank on a sorted list; nil when empty.
+    def percentile(sorted, pct) = sorted.empty? ? nil : sorted[(sorted.size * pct / 100.0).ceil - 1]
+
+    def fold(row, data)
+      row.merge!(data.slice("operation", "agent", "provider", "model", "turn").compact)
+      if data["type"] == "llm_request"
+        row.merge!(data.slice("status", "duration_ms"))
+        row["completed_at"] = Time.iso8601(data.fetch("at")).utc.iso8601(6)
+      else
+        row["attempts"] += 1
+        row["failed_attempts"] += 1 if data["status"] == "failed"
+        VALUES.each do |field|
+          next if data[field].nil?
+
+          row[field] = row.fetch(field, 0) + data[field]
+          row["reported"][field] = row["reported"].fetch(field, 0) + 1
+        end
+      end
+    end
+
+    HOUR = 3600
+    MAX_BUCKETS = 92
+
+    # Fixed periods keep their buckets; a custom range goes hourly up to 2 days,
+    # 6-hourly up to 14, daily beyond (capped, so a year stays a readable chart).
+    def bucket_count(period, span)
+      fixed = { "24h" => 24, "7d" => 28, "30d" => 30 }[period]
+      return fixed if fixed
+
+      base = if span <= 48 * HOUR then HOUR elsif span <= 14 * 24 * HOUR then 6 * HOUR else 24 * HOUR end
+      (span / base).ceil.clamp(1, MAX_BUCKETS)
+    end
+
+    def time_series(rows, from:, to:, period:)
+      count = bucket_count(period, to - from)
+      step = (to - from) / count
+      buckets = Array.new(count) { [] }
+      rows.each do |row|
+        index = [((Time.iso8601(row["completed_at"]) - from) / step).floor, count - 1].min
+        buckets[index] << row
+      end
+      buckets.each_with_index.map do |group, index|
+        summarize(group).merge("at" => (from + index * step).utc.iso8601,
+          "until" => (from + (index + 1) * step).utc.iso8601)
+      end
+    end
+
+    def summarize(rows)
+      durations = rows.filter_map { |row| row["duration_ms"] }.sort
+      result = {
+        "requests" => rows.size, "attempts" => rows.sum { |row| row["attempts"] },
+        "failures" => rows.count { |row| row["status"] == "failed" },
+        "failed_attempts" => rows.sum { |row| row["failed_attempts"] },
+        "retries" => rows.sum { |row| [row["attempts"] - 1, 0].max },
+        "measured_requests" => durations.size
+      }
+      [50, 90, 95].each { |pct| result["p#{pct}_ms"] = percentile(durations, pct) }
+      VALUES.each do |field|
+        values = rows.filter_map { |row| row[field] }
+        result[field] = values.empty? ? nil : values.sum
+        result["unknown_#{field}_requests"] = rows.count do |row|
+          row["attempts"].zero? || row["reported"].fetch(field, 0) < row["attempts"]
+        end
+      end
+      result
+    end
+  end
+end

data/lib/insika/model_registry.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module Insika
+  # RubyLLM's model catalog (ids, context windows, prices) kept in the shared
+  # store instead of the gem's bundled file, which ages with every deploy.
+  #
+  # Two roles:
+  #   - RubyLLM's `model_registry_store` (#read / #write): the catalog lives in
+  #     one place for every worker and survives restarts.
+  #   - a Tick duty (#run): one worker per interval refreshes from the published
+  #     catalog and the configured providers; every other worker reloads the
+  #     stored catalog when it changes. A failed refresh keeps the catalog it had
+  #     and is retried after RETRY_AFTER, never on every tick.
+  class ModelRegistry
+    SCOPE = "model_registry"
+    INTERVAL = 86_400
+    RETRY_AFTER = 3600
+
+    def initialize(store:, interval: INTERVAL, logger: nil,
+                   refresher: -> { RubyLLM::Models.refresh(remote_only: true) })
+      @store = store
+      @interval = interval.to_i
+      @logger = logger
+      @refresher = refresher
+      @loaded = nil
+    end
+
+    # --- RubyLLM model_registry_store -------------------------------------
+
+    def read
+      raw = @store.get(SCOPE, "catalog") or return []
+      RubyLLM::Models::Registry.models_from_data(JSON.parse(raw, symbolize_names: true))
+    end
+
+    # RubyLLM hands a Models registry; stored as JSON so RubyLLM's own reader parses it back.
+    def write(registry)
+      models = registry.respond_to?(:all) ? registry.all : Array(registry)
+      @store.transaction do
+        @store.set(SCOPE, "catalog", JSON.generate(models.map(&:to_h)))
+        @store.set(SCOPE, "meta", { "refreshed_at" => Time.now.utc.iso8601(6), "models" => models.size })
+      end
+    end
+
+    def description = "Insika store (#{SCOPE})"
+
+    # --- Tick duty ---------------------------------------------------------
+
+    # -> { refreshed: true, models: n } | { reloaded: true } | nil (nothing to do)
+    def run(now: Time.now.utc)
+      return nil unless @interval.positive?
+
+      install
+      return refresh if claim(now)
+
+      reload
+    end
+
+    def refreshed_at = @store.get(SCOPE, "meta")&.fetch("refreshed_at", nil)
+
+    private
+
+    # RubyLLM reads and refreshes through the store from here on; a worker that
+    # already loaded the bundled catalog switches on its next #reload.
+    def install
+      require "ruby_llm"
+      RubyLLM.config.model_registry_store = self unless RubyLLM.config.model_registry_store.equal?(self)
+    end
+
+    def refresh
+      @refresher.call
+      @loaded = refreshed_at
+      { refreshed: true, models: RubyLLM.models.all.size }
+    rescue StandardError => e
+      @logger&.warn("model registry refresh failed: #{e.class}: #{e.message}")
+      { refreshed: false, error: e.class.name }
+    end
+
+    def reload
+      stamp = refreshed_at
+      return nil if stamp.nil? || stamp == @loaded
+
+      RubyLLM.models.load_from_store
+      @loaded = stamp
+      { reloaded: true }
+    end
+
+    # One refresher per window across workers (Tick's claim discipline): due once
+    # `refreshed_at` is an interval old, and a failed attempt waits RETRY_AFTER.
+    def claim(now)
+      @store.transaction do
+        attempted = time(@store.get(SCOPE, "claim")&.fetch("attempted_at", nil))
+        refreshed = time(refreshed_at)
+        due = refreshed.nil? || now - refreshed >= @interval
+        next false unless due && (attempted.nil? || now - attempted >= RETRY_AFTER)
+
+        @store.set(SCOPE, "claim", { "attempted_at" => now.iso8601 })
+        true
+      end
+    end
+
+    def time(value)
+      value && Time.iso8601(value.to_s)
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/insika/model_resolver.rb

@@ -164,7 +164,7 @@ module Insika
       out = {}
       params.each do |k, v|
         key = k.to_sym
-        out[key] = v if %i[temperature max_tokens thinking].include?(key)
+        out[key] = v if %i[temperature max_tokens thinking provider_routing].include?(key)
       end
       out
     end

data/lib/insika/model_selection.rb

@@ -37,6 +37,7 @@ module Insika
     def apply_params(chat)
       p = params || {}
       apply(chat, :with_temperature, p[:temperature]) if numeric?(p[:temperature])
+      apply(chat, :with_max_output_tokens, p[:max_tokens]) if numeric?(p[:max_tokens])
       apply_payload_params(chat, p)
       apply_effort(chat, p[:thinking]) if present?(p[:thinking])
       chat
@@ -48,27 +49,22 @@ module Insika
       chat.public_send(method, value) if chat.respond_to?(method)
     end
 
-    # The params that ride RubyLLM's `with_params` (deep-merged OVER the provider
-    # payload, so they win over a provider default). ONE call on purpose:
-    # `with_params` REPLACES the whole hash — a second call would silently drop
-    # the first one's keys.
-    #
-    # max_tokens goes here because the gem has NO with_max_* setter: the chat's
-    # fluent API covers temperature/thinking only, and Anthropic is the only
-    # provider that emits a cap at all (from the model registry, 4096 by default).
-    # `max_tokens` is the wire key for Anthropic and for every OpenAI-compatible
-    # provider (DeepSeek included); OpenAI's o-series wants
-    # `max_completion_tokens` instead — that per-provider mapping is not modelled
-    # yet, and a raw provider key is not authorable (the profile whitelists
-    # temperature/max_tokens/thinking).
+    # Provider-specific controls retain their existing wire shape. Token limits
+    # use RubyLLM's native setter so each protocol chooses its own wire key.
     def apply_payload_params(chat, p)
-      return unless chat.respond_to?(:with_params)
+      return unless chat.respond_to?(:with_provider_options)
 
       payload = {}
-      payload[:max_tokens] = p[:max_tokens] if numeric?(p[:max_tokens])
       toggle = thinking_toggle(p[:thinking])
       payload[:thinking] = { type: toggle } if toggle
-      chat.with_params(**payload) unless payload.empty?
+      # WHICH upstream serves the model, for a gateway that has several. Authored
+      # as `provider_routing` and emitted under the wire key `provider` —
+      # OpenRouter's, the only shape that exists for this today; a provider
+      # without the field ignores an unknown body key. A raw provider key is
+      # not authorable, so the one
+      # capability gets a name of its own.
+      payload[:provider] = p[:provider_routing] if p[:provider_routing].is_a?(Hash)
+      chat.with_provider_options(payload) unless payload.empty?
     end
 
     # The resolved reasoning control (4-layer). Two axes folded into one field:
@@ -78,11 +74,8 @@ module Insika
     # Blank/nil never reaches here (apply_params guards on present?), so no config
     # anywhere = the provider's own default.
     #
-    # ruby_llm 1.16's with_thinking only EMITS reasoning_effort and cannot toggle
-    # on/off; the on/off ride on with_params (deep-merged over the payload). The
-    # thinking:{type:} shape is DeepSeek's OpenAI-compat contract — gated to it
-    # (nil provider = the platform default, DeepSeek here); other providers get
-    # effort-only until their toggle wire is mapped (e.g. Anthropic output_config).
+    # Native on/off requires model-registry controls, which custom DeepSeek ids
+    # may not have. Keep the explicit DeepSeek toggle valid for those models.
     def thinking_toggle(value)
       return nil unless present?(value) && reasoning_toggle_supported?
 

data/lib/insika/model_visible.rb

@@ -20,19 +20,30 @@ module Insika
     # -> ModelVisible. `chat` is the RubyLLM chat at the boundary (instructions,
     # tools, messages are exactly the three parts the provider serializes).
     def self.capture(chat)
+      messages = chat.respond_to?(:messages) ? Array(chat.messages) : []
+      tools = chat.respond_to?(:tools) ? chat.tools : []
       new(
-        instructions: chat.respond_to?(:instructions) ? chat.instructions : nil,
-        tools: chat.respond_to?(:tools) ? Array(chat.tools).map { |t| tool_schema(t) } : [],
-        messages: chat.respond_to?(:messages) ? Array(chat.messages) : []
+        instructions: instructions_of(chat, messages),
+        tools: (tools.is_a?(Hash) ? tools.values : Array(tools)).map { |t| tool_schema(t) },
+        messages: messages
       )
     end
 
-    # -> Hash: the JSON-safe schema of ONE tool. Reads `parameters` then
+    # -> String | nil: the system text the chat sends (the instructions reader, else
+    # its system messages). Also what Safety::PromptEcho compares a reply against.
+    def self.instructions_of(chat, messages = chat.respond_to?(:messages) ? Array(chat.messages) : [])
+      return chat.instructions if chat.respond_to?(:instructions)
+
+      system = messages.select { |m| m.respond_to?(:role) && m.role.to_s == "system" }
+      Coercion.presence(system.map(&:content).join("\n\n"))
+    end
+
+    # -> Hash: the JSON-safe schema of ONE tool. Reads `parameters_schema` then
     # `schema` (the two reader shapes the house FakeChat and the gem's tools
     # answer); a tool answering none degrades to nil, never raises.
     def self.tool_schema(tool)
-      params = if tool.respond_to?(:parameters)
-                 tool.parameters
+      params = if tool.respond_to?(:parameters_schema)
+                 tool.parameters_schema
                elsif tool.respond_to?(:schema)
                  tool.schema
                end

data/lib/insika/onboarding.rb

@@ -55,6 +55,7 @@ module Insika
       "embedding" => "docs/EMBEDDING.md",
       "sandbox" => "docs/SANDBOX.md",
       "benchmark" => "docs/BENCHMARK.md",
+      "rubyllm-2-migration" => "docs/RUBYLLM_2_MIGRATION.md",
       "observability" => "docs/OBSERVABILITY.md",
       "schedules" => "docs/SCHEDULING.md",
       "artifacts" => "docs/ARTIFACTS.md",

data/lib/insika/outcome_store.rb

@@ -43,7 +43,7 @@ module Insika
     # the no-tenant records must pass `tenant: ""` explicitly (the FOLD uses
     # `for_pair`, never this nil-means-everything trap).
     def all(tenant: nil, agent: nil)
-      records = @store.list(SCOPE).filter_map { |k| to_record(@store.get(SCOPE, k)) }
+      records = @store.entries(SCOPE).filter_map { |_k, rec| to_record(rec) }
       records.select! { |r| r.tenant == tenant } if tenant
       records.select! { |r| r.agent == agent } if agent
       records.sort_by(&:at).reverse

data/lib/insika/overlay_tool_registry.rb

@@ -27,8 +27,10 @@ module Insika
   # are "data-defined" or MCP-discovered.
   class OverlayToolRegistry
     def initialize(base:, tool_store:, http:, egress: Insika::EgressGuard, egress_options: {}, event_stream: nil,
-                   mcp_registry: nil)
+                   mcp_registry: nil, recheck: 2, clock: -> { Process.clock_gettime(Process::CLOCK_MONOTONIC) })
       @base = base
+      @recheck = recheck
+      @clock = clock
       @tool_store = tool_store
       @http = http
       @egress = egress
@@ -70,16 +72,37 @@ module Insika
     # Atomic swap of the dynamic index (after writing/removing a data-tool).
     def reload
       @dynamic = build_dynamic
+      @token = @tool_store.version_token
+      @checked_at = @clock.call
       self
     end
 
+    # Changes when the data-tools were rebuilt; a catalog over this registry
+    # compares it to know its own index is stale.
+    def generation
+      dynamic
+      @token
+    end
+
     # Is it a CODE tool (base)? Used by the authoring Command's validation.
     def code_tool?(name) = @base.names.include?(name.to_s)
 
     private
 
+    # Another worker may have written a data-tool (import, Studio edit): at most
+    # every `recheck` seconds, compare the config version token and rebuild when it
+    # moved. The token moves on any config write, so a rebuild may find nothing new.
     def dynamic
-      @dynamic ||= build_dynamic
+      reload if @dynamic.nil? || stale?
+      @dynamic
+    end
+
+    def stale?
+      now = @clock.call
+      return false if now - @checked_at < @recheck
+
+      @checked_at = now
+      @tool_store.version_token != @token
     end
 
     # No I/O (McpToolRegistry#entries only reads McpStore#tools_cache) ->
@@ -112,6 +135,11 @@ module Insika
     # Lazy require: DataDefinedTool inherits from RubyLLM::Tool (pulls in the gem) -> kept
     # out of insika.rb load-time, loaded on the 1st instance (turn time).
     def build_tool(definition)
+      if definition.presentation?
+        require_relative "tools/present"
+        return Insika::Tools::Present.new(definition: definition, event_stream: @event_stream)
+      end
+
       require_relative "tools/data_defined_tool"
       Insika::Tools::DataDefinedTool.new(
         definition: definition, http: @http, egress: @egress,