insika 0.8.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

@@ -72,7 +72,7 @@ module Insika
         stats = tool_stats(sessions[id] || [], cutoff)
         never_called_rows(id, record, stats) +
           error_rate_rows(id, stats, days) +
-          stale_rows(id, stats)
+          stale_rows(id, stats) + blocked_rows(id, stats, days)
       end
 
       Report.new(generated_at: now.iso8601, days: days,
@@ -100,7 +100,7 @@ module Insika
     # 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 } }
+      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]
@@ -113,6 +113,7 @@ module Insika
 
           s[:window_calls] += 1
           s[:window_errors] += 1 if error
+          s[:blocked][entry["gate"]] += 1 if entry["gate"]
         end
       end
       stats
@@ -142,6 +143,15 @@ module Insika
       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?

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,

data/lib/insika/tools/tool_search.rb

@@ -21,7 +21,7 @@ module Insika
       def name = "tool_search"
 
       def initialize(catalog, deferred_allowed, chat, tool_registry:, event_stream:,
-                     checkpoint_store:, state:)
+                     checkpoint_store:, state:, trace_recorder: nil)
         @catalog = catalog
         @deferred_allowed = Array(deferred_allowed).map(&:to_s)
         @chat = chat
@@ -29,6 +29,7 @@ module Insika
         @event_stream = event_stream
         @checkpoint_store = checkpoint_store
         @state = state
+        @trace_recorder = trace_recorder
         @promoted = [] # names already promoted IN THIS chat — idempotency
         super()
       end
@@ -59,7 +60,8 @@ module Insika
           @promoted << entry.name
           ToolEnvelope.new(tool, state: @state, checkpoint_store: @checkpoint_store,
                                  tool_registry: @tool_registry, timeout: timeout,
-                                 skip_side_effects: Array(@state.skip_side_effects))
+                                 skip_side_effects: Array(@state.skip_side_effects),
+                                 event_stream: @event_stream, trace_recorder: @trace_recorder)
         rescue Insika::NotFoundError
           nil
         end

data/lib/insika/turn_state.rb

@@ -61,9 +61,16 @@ module Insika
                   #                      context via an evidence-declared tool (the envelope
                   #                      appends; the validator/enforcer read it). Built per
                   #                      turn by the Executor; nil = no session/no evidence.
-                  :evidence_attachments, # [ {type, url, caption} ] hoarded by the
+                  :evidence_attachments, # [ {type, url, caption, id} ] hoarded by the
                   #                      envelope this turn; read by the Executor at stage 8
                   #                      for the channel delivery. Reset per turn.
+                  :presentations,      # [ {component, title, items: [{id,url,caption}]} ] —
+                  #                      what a presentation tool SELECTED this turn, in call
+                  #                      order. Non-empty = the channel delivery sends these
+                  #                      instead of every hoarded card. Reset per turn.
+                  :fence_max_chars,    # per-leaf cap the ToolEnvelope applies when the
+                  #                      agent has `fencing` on — the platform's
+                  #                      `fencing.max_chars`, set per turn by the Executor.
                   :context_trace_entry  # the sanitized trace entry parked at
                   #                      prepare_turn (fingerprints + invalidation_reason);
                   #                      the stage-8 stamp merges the cache-hit fields into
@@ -167,6 +174,10 @@ module Insika
     # nil = concurrency off: no gate, no overhead, serial execution unchanged.
     attr_accessor :tool_gate
 
+    # Turns of one session already run serially through SessionActor. This gate
+    # prevents overlapping writes within a parallel batch of the current turn.
+    attr_accessor :side_effect_gate
+
     # parallel tool calls, resolved PER TURN and read by ChatBuilder
     # (whether to hand the gem `concurrency:`) and ToolAssembly (the gate's size).
     #
@@ -199,6 +210,7 @@ module Insika
       @output_parts = []
       @channel_capabilities = []
       @evidence_attachments = []
+      @presentations = []
       # Fiber storage is INHERITED by fibers created later, so a turn spawned from
       # inside a tool call (a subagent child) would start out carrying its
       # parent's correlation. Clearing at turn start keeps a child from keying its

data/lib/insika/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Insika
-  VERSION = "0.8.0"
+  VERSION = "0.9.0"
 end

data/lib/insika/wiring/graph.rb

@@ -422,6 +422,13 @@ module Insika
         bus = Insika::CommandBus.new
         bus.register(:create_session,
                      Insika::Commands::CreateSession.new(session_store: spine.session_store, event_stream: spine.event_stream))
+        # A snapshot loaded into a conversation before its first turn — what an eval
+        # case declares as `state:`. The HTTP route and the in-process eval transport
+        # both dispatch this one command.
+        bus.register(:seed_session,
+                     Insika::Commands::SeedSession.new(session_store: spine.session_store,
+                                                       memory_store: spine.memory_store,
+                                                       event_stream: spine.event_stream))
         bus.register(:cancel_task,
                      Insika::Commands::CancelTask.new(task_store: spine.task_store, executor: executor))
         bus.register(:pause_task,

data/lib/insika/wiring/graph_chat.rb

@@ -18,6 +18,10 @@ module Insika
         @graph = graph
       end
 
+      # The graph this seam speaks for — an eval transport reaches its bus and
+      # event stream through here.
+      attr_reader :graph
+
       # One turn, in-process -> the assistant's text. `agent:` is REQUIRED —
       # this seam has no notion of "the default agent" (that is a DSL::Runtime
       # concept, filled in by its own caller before delegating here). Raises

data/lib/insika.rb

@@ -99,6 +99,7 @@ require_relative "insika/context/catalog_provider"
 require_relative "insika/context/builder"
 require_relative "insika/context/providers/request"
 require_relative "insika/context/providers/prompt"
+require_relative "insika/context/providers/fence_notice"
 require_relative "insika/context/providers/skill"
 require_relative "insika/context/providers/skill_trigger"
 require_relative "insika/context/providers/tool_search"
@@ -230,6 +231,7 @@ require_relative "insika/system_file_store"
 require_relative "insika/recovery"
 require_relative "insika/command_bus"
 require_relative "insika/commands/create_session"
+require_relative "insika/commands/seed_session"
 require_relative "insika/commands/cancel_task"
 require_relative "insika/commands/pause_task"
 require_relative "insika/commands/approve_action"
@@ -345,6 +347,8 @@ require_relative "insika/turn_output"
 require_relative "insika/turn_state"
 require_relative "insika/turn_timing"
 require_relative "insika/capability/resolved_tool"
+require_relative "insika/fence"
+require_relative "insika/spoken_transcript"
 require_relative "insika/tool_envelope"
 require_relative "insika/tool_assembly"
 require_relative "insika/chat_builder"