insika 0.7.0 → 0.9.0

data/lib/insika/tool_definition.rb

@@ -35,7 +35,9 @@ module Insika
   ToolDefinition = Data.define(
     :name, :description, :parameters, :request, :response,
     :secret_headers, :side_effect, :timeout, :group, :tags, :halt_when,
-    :evidence                       # Insika::Evidence::Spec | nil
+    :evidence,                      # Insika::Evidence::Spec | nil
+    :requires_evidence,             # { "params" => [String] } | nil
+    :presentation                   # { component:, ids:, max: } | nil — a UI tool, no HTTP
   )
 
   class ToolDefinition
@@ -73,9 +75,9 @@ module Insika
     # Builds + validates. Raises Insika::ValidationError. Accepts keyword args
     # (already-normalized symbol keys); use from_h for a raw Hash from the store/UI.
     # `parameters` accepts JSON Schema (Hash) OR the legacy flat array.
-    def self.build(name:, description:, request:, parameters: nil, response: nil,
+    def self.build(name:, description:, request: nil, parameters: nil, response: nil,
                    secret_headers: nil, side_effect: nil, timeout: nil, group: nil, tags: nil,
-                   halt_when: nil, evidence: nil)
+                   halt_when: nil, evidence: nil, presentation: nil, requires_evidence: nil)
       name = name.to_s
       raise Insika::ValidationError, "name must match #{NAME_RE.inspect}" unless NAME_RE.match?(name)
 
@@ -83,15 +85,21 @@ module Insika
       raise Insika::ValidationError, "description is required" if desc.empty?
 
       schema = normalize_params(parameters)
-      req = normalize_request(request, top_level_names(schema))
+      # A tool is EITHER an HTTP call or a presentation — never both, never neither.
+      if request && presentation
+        raise Insika::ValidationError, "a tool declares either 'request' or 'presentation', not both"
+      end
+
+      pres = normalize_presentation(presentation, schema)
+      req = pres ? nil : normalize_request(request || {}, top_level_names(schema))
       resp = normalize_response(response)
       if resp[:extract] == "evidence_envelope" && evidence.nil?
         raise Insika::ValidationError,
               "extract 'evidence_envelope' requires an 'evidence' declaration"
       end
 
-      method = req[:method]
-      effect = side_effect.nil? ? !IDEMPOTENT.include?(method) : (side_effect ? true : false)
+      method = req && req[:method]
+      effect = side_effect.nil? ? !(method.nil? || IDEMPOTENT.include?(method)) : (side_effect ? true : false)
 
       new(
         name: name, description: desc, parameters: schema, request: req, response: resp,
@@ -99,7 +107,9 @@ module Insika
         timeout: timeout.nil? ? nil : Integer(timeout),
         group: normalize_group(group), tags: normalize_tags(tags),
         halt_when: normalize_halt_when(halt_when),
-        evidence: Insika::Evidence::Spec.parse(evidence)
+        evidence: Insika::Evidence::Spec.parse(evidence),
+        presentation: pres,
+        requires_evidence: normalize_requires_evidence(requires_evidence, top_level_names(schema))
       )
     end
 
@@ -108,12 +118,63 @@ module Insika
       h = deep_symbolize(hash)
       build(
         name: h[:name], description: h[:description], parameters: h[:parameters],
-        request: h[:request] || {}, response: h[:response],
+        request: h[:request], response: h[:response],
         secret_headers: h[:secret_headers], side_effect: h[:side_effect], timeout: h[:timeout],
-        group: h[:group], tags: h[:tags], halt_when: h[:halt_when], evidence: h[:evidence]
+        group: h[:group], tags: h[:tags], halt_when: h[:halt_when], evidence: h[:evidence],
+        presentation: h[:presentation], requires_evidence: h[:requires_evidence]
       )
     end
 
+    # PRESENTATION: a tool whose job is to SHOW something, not to fetch it. The model
+    # picks ids, the engine validates them against the session's evidence ledger and
+    # joins the cards an evidence tool already returned (Tools::Present). No HTTP.
+    #
+    #   "presentation" => { "component" => "product_cards",   # what the channel renders
+    #                       "ids" => "product_ids",           # the array:string param
+    #                       "max" => 8 }                      # 1..16, the attachment cap
+    #
+    # -> { component:, ids:, max: } | nil
+    def self.normalize_presentation(raw, schema)
+      return nil if raw.nil?
+
+      h = deep_symbolize(raw)
+      raise Insika::ValidationError, "presentation must be an object" unless h.is_a?(Hash)
+
+      component = h[:component].to_s
+      unless NAME_RE.match?(component)
+        raise Insika::ValidationError, "presentation.component must match #{NAME_RE.inspect}"
+      end
+
+      ids = h[:ids].to_s
+      prop = (schema["properties"] || {})[ids]
+      unless prop.is_a?(Hash) && prop["type"] == "array" && prop.dig("items", "type") == "string"
+        raise Insika::ValidationError,
+              "presentation.ids must name a declared array:string parameter (got #{ids.inspect})"
+      end
+
+      max = h[:max].nil? ? Insika::Evidence::MAX_ATTACHMENTS : Integer(h[:max], exception: false)
+      unless max.is_a?(Integer) && max.between?(1, Insika::Evidence::MAX_ATTACHMENTS)
+        raise Insika::ValidationError, "presentation.max must be 1..#{Insika::Evidence::MAX_ATTACHMENTS}"
+      end
+
+      { component: component, ids: ids, max: max }
+    end
+    private_class_method :normalize_presentation
+
+    def presentation? = !presentation.nil?
+
+    def self.normalize_requires_evidence(value, param_names)
+      return nil if value.nil?
+
+      params = value.is_a?(Hash) ? deep_symbolize(value)[:params] : value
+      unless params.is_a?(Array) && !params.empty? && params.all? { |p| param_names.include?(p.to_s) }
+        raise Insika::ValidationError, "requires_evidence needs a non-empty list of declared top-level parameters"
+      end
+
+      { "params" => params.map(&:to_s).uniq }
+    end
+    private_class_method :normalize_requires_evidence
+
     # Group: enablement label by DATA (not name convention),
     # target of AgentProfile's `tools_allow_groups`. Trimmed; empty/nil -> nil.
     def self.normalize_group(group)
@@ -414,7 +475,7 @@ module Insika
       h = {
         "name" => name, "description" => description,
         "parameters" => parameters,
-        "request" => request.transform_keys(&:to_s),
+        "request" => request&.transform_keys(&:to_s),
         "response" => response.transform_keys(&:to_s),
         "secret_headers" => secret_headers,
         "side_effect" => side_effect, "timeout" => timeout,
@@ -424,6 +485,8 @@ module Insika
       # present only when declared — a tool without evidence is byte-identical
       # to today (no declaration, no envelope processing).
       h["evidence"] = evidence.to_h if evidence
+      h["requires_evidence"] = requires_evidence if requires_evidence
+      h["presentation"] = presentation.transform_keys(&:to_s) if presentation
       h
     end
 

data/lib/insika/tool_envelope.rb

@@ -12,6 +12,10 @@ module Insika
   # The tool loop belongs to RubyLLM; this is a decorator over the instances —
   # the Executor never drives roundtrips.
   class ToolEnvelope < SimpleDelegator
+    PROVENANCE_INSTRUCTION = "This value was not returned by any tool in this conversation. " \
+                             "Find it with a tool that returns it — a search or a lookup by id — " \
+                             "then call this tool again with an id from that result."
+
     # The tool timeout's OWN class: distinct from Async::TimeoutError so that
     # the rescue below NEVER swallows the TURN timeout (which uses the default of
     # with_timeout). Without this, a turn overflowing while the fiber is inside a
@@ -20,13 +24,21 @@ module Insika
     ToolTimeout = Class.new(StandardError)
     private_constant :ToolTimeout
 
+    # A gate's refusal. A plain Hash subclass: it reaches the model exactly as the
+    # `{status:, gate:, ...}` it always was, and the engine's own readers (the
+    # :tool_result outcome, the trace) recognize a refusal by CLASS — a data tool
+    # answering `{"status":"blocked","gate":"fraud_review"}` for a held order is
+    # not one, whatever keys it happens to use.
+    class Blocked < Hash; end
+
     def initialize(tool, state:, checkpoint_store:, tool_registry:, timeout:,
-                   skip_side_effects: [], trace_recorder: nil)
+                   skip_side_effects: [], trace_recorder: nil, event_stream: nil)
       super(tool)
       @state = state
       @checkpoint_store = checkpoint_store
       @tool_registry = tool_registry
       @timeout = timeout
+      @event_stream = event_stream
       @skip_side_effects = Array(skip_side_effects) # ids already completed in the interrupted turn
       @trace_recorder = trace_recorder # duck-type: #record(session_id:, entry:). nil = no trace.
     end
@@ -41,6 +53,13 @@ module Insika
       call_id = correlation_id
       return { "skipped" => "already_executed" } if call_id && @skip_side_effects.include?(call_id)
 
+      started = monotonic
+      if (blocked = provenance_block(args))
+        trace(call_id, args, blocked, started)
+        emit_blocked(blocked)
+        return blocked
+      end
+
       # Approval gate: a tool marked `approval` suspends the turn in
       # :waiting until the operator resolves it. Delegates to the coordinator (the
       # Executor), which creates/queries the PendingAction and blocks via the
@@ -61,6 +80,7 @@ module Insika
       # on the ledger, hoard the attachments. No evidence = the result passes
       # through untouched (one nil-check — parity).
       result = process_evidence(result)
+      result = fence(result)
       record_side_effect!(call_id) if side_effect?
       trace(call_id, args, result, started)
       result
@@ -83,7 +103,59 @@ module Insika
     # wall-clock the model waited. No gate (the default, serial) = straight through.
     def with_gate(&)
       gate = @state.respond_to?(:tool_gate) ? @state.tool_gate : nil
-      gate ? gate.acquire(&) : yield
+      return yield unless gate
+
+      serial = @state.respond_to?(:side_effect_gate) ? @state.side_effect_gate : nil
+      return gate.acquire(&) unless side_effect? && serial
+
+      # Backends may read-modify-write. Serialize writes before taking a slot,
+      # so queued writes cannot keep independent reads from running.
+      serial.acquire { gate.acquire(&) }
+    end
+
+    def provenance_block(args)
+      tool = __getobj__
+      requirement = tool.respond_to?(:requires_evidence) ? tool.requires_evidence : nil
+      return unless requirement
+
+      ledger = @state.respond_to?(:evidence_ledger) ? @state.evidence_ledger : nil
+      known = ledger ? ledger.ids : []
+      optional = optional_params(tool)
+      requirement.fetch("params").each do |param|
+        value = args.key?(param) ? args[param] : args[param.to_sym]
+        # A parameter the schema marks optional and the model left out carries no
+        # id to ground — nothing to check (a REQUIRED one left out is still a
+        # block: the write would run without the id the gate exists for).
+        next if value.nil? && ledger && optional.include?(param)
+
+        values = value.is_a?(Array) ? value : [value]
+        values = [nil] if values.empty? && !ledger
+        values.each do |id|
+          next if ledger && known.include?(id.to_s)
+
+          return Blocked[{ "status" => "blocked", "gate" => "provenance", "param" => param,
+                           "value" => id.to_s, "instruction" => PROVENANCE_INSTRUCTION }]
+        end
+      end
+      nil
+    end
+
+    # The wrapped tool's top-level parameters NOT in the schema's `required`
+    # (DataDefinedTool exposes its definition's schema; a code tool exposes none
+    # -> every declared parameter is treated as required).
+    def optional_params(tool)
+      return [] unless tool.respond_to?(:params_schema) && (schema = tool.params_schema).is_a?(Hash)
+
+      (schema["properties"] || {}).keys.map(&:to_s) - Array(schema["required"]).map(&:to_s)
+    end
+
+    def emit_blocked(result)
+      task = @state.task # nil on a one-shot turn, like `trace` already assumes
+      @event_stream&.emit(Insika::Event.new(
+        type: :tool_blocked,
+        data: { name: real_name, gate: result["gate"], param: result["param"] },
+        meta: task ? { task_id: task.id, session_id: task.session_id } : {}
+      ))
     end
 
     # Records the call for debugging in the Studio (name + model args + result +
@@ -96,6 +168,7 @@ module Insika
         session_id: @state.task.session_id,
         entry: { "turn" => @state.turn, "tool" => real_name, "call_id" => call_id.to_s,
                  "args" => args, "result" => result,
+                 "gate" => result.is_a?(Blocked) ? result["gate"] : nil,
                  "ms" => started ? ((monotonic - started) * 1000).round : nil,
                  "at" => Time.now.utc.iso8601 }
       )
@@ -142,6 +215,31 @@ module Insika
                                                            tool_call_id: call_id)
     end
 
+    # ----   fencing ----------------------------------------------
+
+    # After the evidence reshape (the lean envelope is already the shape the
+    # model reads): every String leaf sanitized, keys and non-strings untouched,
+    # each leaf capped at the platform's `fencing.max_chars`. Off = bytes
+    # identical to today. An error hash is engine-authored — never touched.
+    def fence(result)
+      return result unless Insika::Fence.enabled?(@state.profile)
+      return result if result.is_a?(Hash) && (result[:error] || result["error"])
+
+      max = (@state.respond_to?(:fence_max_chars) && @state.fence_max_chars) || Insika::Fence::DEFAULT_MAX_CHARS
+      return Insika::Fence.sanitize_value(result, max_chars: max) unless lean_evidence?(result)
+
+      # A lean evidence result: the LINES are third-party text, the IDS are keys.
+      # The ledger recorded the ids byte-exact and a presentation or a write joins
+      # on them, so NFKC must not touch them (a fullwidth digit in a SKU would
+      # stop matching the moment the model repeated it).
+      items = result["items"].map { |i| i.merge("line" => Insika::Fence.sanitize_text(i["line"].to_s, max_chars: max)) }
+      result.merge("items" => items)
+    end
+
+    def lean_evidence?(result)
+      evidence_spec && result.is_a?(Hash) && result["items"].is_a?(Array)
+    end
+
     # ----   evidence ---------------------------------------------
 
     # The evidence spec for the wrapped tool (D4). Resolution order:
@@ -204,6 +302,8 @@ module Insika
 
       @state.evidence_attachments ||= []
       @state.evidence_attachments.concat(attachments)
+      ledger = @state.respond_to?(:evidence_ledger) ? @state.evidence_ledger : nil
+      ledger.record_cards(attachments) if ledger.respond_to?(:record_cards)
     end
   end
 end

data/lib/insika/tool_store.rb

@@ -55,10 +55,13 @@ module Insika
       raise Insika::ValidationError, "tool '#{name}' already exists" if create_only && existing
 
       final = definition.to_h
-      final["request"]["headers"] = reconcile_secret_headers(
-        final["request"]["headers"], definition.secret_headers,
-        existing&.dig("definition", "request", "headers")
-      )
+      # A presentation tool makes no request — nothing to reconcile.
+      if final["request"]
+        final["request"]["headers"] = reconcile_secret_headers(
+          final["request"]["headers"], definition.secret_headers,
+          existing&.dig("definition", "request", "headers")
+        )
+      end
 
       rec = build_record(final, existing)
       @cs.put(SCOPE, name, rec)
@@ -110,6 +113,8 @@ module Insika
       secret = definition["secret_headers"] || []
       return definition if secret.empty?
 
+      return definition unless definition["request"]
+
       headers = (definition.dig("request", "headers") || {}).each_with_object({}) do |(k, v), acc|
         acc[k] = secret.include?(k) ? SecretMasking.mask(v) : v
       end

data/lib/insika/tool_trace_store.rb

@@ -52,7 +52,7 @@ module Insika
         "ok" => ok?(e["result"]),
         "args" => clip(mask(e["args"])), "result" => clip(mask(e["result"])),
         "ms" => e["ms"], "at" => e["at"].to_s
-      }
+      }.tap { |trace| trace["gate"] = e["gate"].to_s if e["gate"] }
     end
 
     # Conventional tool error = Hash with key "error"/:error (everything else is ok).

data/lib/insika/tool_usage_report.rb

@@ -0,0 +1,172 @@
+# 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) + blocked_rows(id, stats, days)
+      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, blocked: Hash.new(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
+          s[:blocked][entry["gate"]] += 1 if entry["gate"]
+        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 blocked_rows(agent, stats, days)
+      stats.flat_map do |tool, s|
+        s[:blocked].map do |gate, count|
+          Row.new(agent: agent, tool: tool, kind: "blocked",
+                  detail: "#{count} call(s) blocked by #{gate} in the last #{days} day(s)")
+        end
+      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

data/lib/insika/tools/data_defined_tool.rb

@@ -47,6 +47,7 @@ module Insika
       # envelope's duck-typed resolution checks this FIRST — a data-tool declares
       # its evidence on its definition, never in the registry metadata.
       def evidence = @definition.evidence
+      def requires_evidence = @definition.requires_evidence
 
       # FULL (nested) JSON Schema straight into RubyLLM's params_schema — it is what
       # the providers serialize (OpenAI/Anthropic/Gemini/Bedrock prefer

data/lib/insika/tools/present.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # PRESENTATION tool: the model says WHICH products to show, the engine decides
+    # WHAT is shown. Built by the overlay registry from a ToolDefinition that
+    # declares `presentation` (one class, N instances — like DataDefinedTool).
+    #
+    # Cards used to be a side effect of evidence: every attachment a search tool
+    # returned rode the channel delivery, all of them, and the model had no way to
+    # say "these three, not the ten I searched". The deployments compensated with
+    # inline markers in the text, parsed by regex on their side — where most of
+    # the hallucinated ids came from. Here text never carries product data: the
+    # model picks ids, and the engine
+    #   1. keeps only ids the session's evidence ledger has seen (provenance),
+    #   2. joins each to the card the evidence tool already hoarded this turn,
+    #   3. caps at the declared `max`,
+    #   4. records the selection on the turn (the delivery sends THAT),
+    #   5. emits `:ui` on the stream (the edge publishes it as `insika.ui`),
+    #   6. tells the model what was shown and what was dropped, and why.
+    # No HTTP, no model call, deterministic. `execute` never raises.
+    class Present < RubyLLM::Tool
+      # The one sentence for the model when NOTHING could be shown. Engine-generic:
+      # the pack tunes vocabulary through the tool's `description`.
+      NOTHING_SHOWN = "no card could be shown; name the products in text or search again"
+
+      def initialize(definition:, event_stream: nil)
+        @definition = definition
+        @event_stream = event_stream
+        @state = nil
+        super()
+      end
+
+      # Deposited by ToolAssembly before the envelope wraps the instance — the
+      # ledger and the hoarded cards live on the turn, never on the registry.
+      def turn_state=(state)
+        @state = state
+      end
+
+      def name = @definition.name
+      def description = @definition.description
+      def params_schema = @definition.parameters
+
+      def parameters
+        @parameters ||= @definition.top_level_params.each_with_object({}) do |p, acc|
+          sym = p[:name].to_sym
+          acc[sym] = RubyLLM::Parameter.new(sym, type: p[:type], desc: p[:description], required: p[:required])
+        end
+      end
+
+      def execute(**kwargs)
+        spec = @definition.presentation
+        ids = Array(kwargs[spec[:ids].to_sym]).map(&:to_s).reject(&:empty?).uniq
+        title = Coercion.presence(kwargs[:title])
+
+        shown, dropped = select(ids, spec[:max])
+        record(spec[:component], title, shown)
+        emit(spec[:component], title, shown, dropped)
+
+        out = { "shown" => shown.map { |c| c["id"] }, "dropped" => dropped }
+        out["instruction"] = NOTHING_SHOWN if shown.empty?
+        out
+      rescue StandardError => e
+        { error: "presentation failed: #{e.message}" }
+      end
+
+      private
+
+      # -> [shown cards, dropped [{id, reason}]]. Order preserved. Reasons:
+      #   unknown — the ledger never saw the id (the model made it up, or the
+      #             customer typed it); no ledger on the state reads as unknown too —
+      #             a check that cannot verify does not pass.
+      #   no_card — the id is known but no evidence tool returned a card for it
+      #             this session (a text-only search result, or a seed of ids alone).
+      #   max     — beyond the declared cap.
+      # Cards come from this turn first, then from the ledger (the last few
+      # searches of the session) — "show me the second one" a turn later works.
+      def select(ids, max)
+        ledger = @state.respond_to?(:evidence_ledger) ? @state.evidence_ledger : nil
+        known = Array(ledger&.ids)
+        turn_cards = @state.respond_to?(:evidence_attachments) ? Array(@state.evidence_attachments) : []
+        session_cards = ledger.respond_to?(:cards) ? Array(ledger.cards) : []
+        by_id = (turn_cards + session_cards).each_with_object({}) { |c, h| h[c["id"]] ||= c if c["id"] }
+
+        shown = []
+        dropped = []
+        ids.each do |id|
+          if !known.include?(id) then dropped << { "id" => id, "reason" => "unknown" }
+          elsif (card = by_id[id]).nil? then dropped << { "id" => id, "reason" => "no_card" }
+          elsif shown.size >= max then dropped << { "id" => id, "reason" => "max" }
+          else shown << card
+          end
+        end
+        [shown, dropped]
+      end
+
+      def record(component, title, shown)
+        return unless @state.respond_to?(:presentations)
+
+        @state.presentations ||= []
+        @state.presentations << { "component" => component, "title" => title,
+                                  "items" => shown.map { |c| c.slice("id", "type", "url", "caption") } }
+      end
+
+      def emit(component, title, shown, dropped)
+        return unless @event_stream
+
+        task = @state.respond_to?(:task) ? @state.task : nil
+        meta = task ? { task_id: task.id, session_id: task.session_id } : {}
+        @event_stream.emit(Insika::Event.new(
+                             type: :ui,
+                             data: { component: component, title: title,
+                                     items: shown.map { |c| c.slice("id", "type", "url", "caption") },
+                                     count: shown.size, dropped: dropped },
+                             meta: meta
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/tools/run_persona_eval.rb

@@ -161,7 +161,7 @@ module Insika
         simulator = Insika::Evals::Simulator.new(transport: transport, ask: persona_ask, safety: safety)
 
         conv = "eval-#{golden.id}-#{SecureRandom.hex(4)}" # a fresh session every run (never reused)
-        run = simulator.run(persona: golden.persona, agent: golden.agent, conv: conv)
+        run = simulator.run(persona: golden.persona, agent: golden.agent, conv: conv, state: golden.state)
         verdict = judge.score_conversation(
           rubric: golden.rubric, transcript: run.transcript, policy: golden.policy,
           min_score: golden.min_score || Insika::Evals::Judge::DEFAULT_MIN_SCORE
@@ -199,6 +199,11 @@ module Insika
           llm: llm_context
         )
         bus = Insika::CommandBus.new
+        # a golden with `state:` seeds through the same bus the turn runs on
+        bus.register(:seed_session, Insika::Commands::SeedSession.new(
+                                       session_store: @graph.session_store, memory_store: @graph.memory_store,
+                                       event_stream: @graph.event_stream
+                                     ))
         bus.register(:send_message, Insika::Commands::SendMessage.new(
                                        profiles: @graph.profiles, session_store: @graph.session_store,
                                        task_store: @graph.task_store, executor: executor,