insika 0.8.0 → 0.9.0

data/lib/insika/evals/transport.rb

@@ -22,6 +22,11 @@ module Insika
     # different facts, and a budget that confuses them stops being a budget.
     TurnOutcome = Struct.new(:result, :ttfb, :total, :usage, keyword_init: true)
 
+    # The deployment answered the seed with a refusal (403: `evals.seeding` is off
+    # there). Its own class so the Runner can SKIP the case with the reason — a
+    # different fact from a seed that failed (409, 5xx, network), which fails it.
+    class SeedRefused < Insika::Error; end
+
     # Pure reduction of the /v1/responses SSE stream. Kept separate from the HTTP so
     # it's testable offline with canned frames (server/responses.rb is the producer).
     module Sse
@@ -47,28 +52,67 @@ module Insika
 
       # [payload] -> { output_text:, tool_calls:, usage:, error: }. Maps the Responses
       # frames (see server/responses.rb#frame_for): text deltas accumulate; each
-      # function_call item contributes a tool NAME (this stream carries no per-tool
-      # status — that lives in the ToolTraceStore, an in-process enrichment); a
-      # `response.failed` sets the turn error.
+      # function_call `added` item opens a tool call (name + arguments); its `done`
+      # item closes it with how the call ended (status ok/error/blocked + the gate
+      # that held it). An older deployment sends `added` only, and the entries keep
+      # `status: nil` — the shape widened, nothing moved. A `response.failed` sets
+      # the turn error.
       def reduce(payloads)
         text = +""
         tools = []
+        by_id = {}
+        ui = []
         usage = nil
         error = nil
         payloads.each do |o|
           case o["type"]
           when "response.output_text.delta"
             text << o["delta"].to_s
+          when "insika.ui"
+            # A presentation tool's selection — the component and how many cards it
+            # showed. The `ui_components`/`no_ui` graders read this.
+            ui << { "component" => o["component"].to_s, "count" => o["count"].to_i }
           when "response.output_item.added"
             item = o["item"] || {}
-            tools << { "name" => item["name"].to_s, "status" => nil } if item["type"] == "function_call"
+            next unless item["type"] == "function_call"
+
+            entry = { "name" => item["name"].to_s, "status" => nil }
+            (args = arguments_of(item["arguments"])) && (entry["arguments"] = args)
+            tools << entry
+            (id = item["call_id"]) && (by_id[id] = entry)
+          when "response.output_item.done"
+            item = o["item"] || {}
+            next unless item["type"] == "function_call"
+
+            # Paired by call_id. An older engine's frames carry none: then the FIRST
+            # still-open call of that name (a batch runs concurrently and its `done`
+            # frames arrive in completion order). No `added` at all = a system tool
+            # the engine reports the end of but never announced (load_skill): not a
+            # tool call here, exactly as it is not one in the in-process transport.
+            entry = by_id[item["call_id"]] || tools.find { |t| t["name"] == item["name"].to_s && t["status"].nil? }
+            next unless entry
+
+            entry["status"] = item["status"].to_s
+            entry["gate"] = item["gate"].to_s if item["gate"]
           when "response.completed"
             usage = o.dig("response", "usage")
           when "response.failed"
             error = o.dig("response", "error", "message") || "response.failed"
           end
         end
-        { output_text: text, tool_calls: tools, usage: usage, error: error }
+        { output_text: text, tool_calls: tools, ui: ui, usage: usage, error: error }
+      end
+
+      # The item's `arguments` is a JSON string on the wire (the OpenAI shape); the
+      # graders want the Hash. Anything unparseable stays the raw string — the call
+      # happened, and a report should still show what it saw. nil when absent.
+      def arguments_of(raw)
+        return nil if raw.nil?
+        return raw unless raw.is_a?(String)
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        raw
       end
     end
 
@@ -160,14 +204,50 @@ module Insika
 
         reduced = Sse.reduce(Sse.payloads(buffer))
         TurnOutcome.new(
-          result: TurnResult.new(output_text: reduced[:output_text],
-                                 tool_calls: reduced[:tool_calls], error: reduced[:error]),
+          result: TurnResult.new(output_text: reduced[:output_text], tool_calls: reduced[:tool_calls],
+                                 ui: reduced[:ui], error: reduced[:error]),
           ttfb: ttfb, total: (mono - t0) * 1000.0, usage: reduced[:usage]
         )
       rescue StandardError => e
         failure(e.class.to_s, t0)
       end
 
+      # Loads a case's `state:` into the conversation BEFORE its first turn —
+      # `POST /v1/conversations/:conv/seed`, the same Bearer as the turn, so the
+      # seeded session is the one the turn continues. The body is the state mapping
+      # (+ `customer` when the turns will carry one). A 403 is the deployment
+      # refusing to seed (`evals.seeding` off) -> SeedRefused, which the Runner
+      # turns into a skip; anything else that is not 2xx is an error that fails the
+      # case — a seed that did not land must never let the case run empty and pass.
+      def seed(conv, state, customer: nil)
+        uri = URI.join("#{@base}/", "v1/conversations/#{URI.encode_www_form_component(conv)}/seed")
+        req = Net::HTTP::Post.new(uri)
+        req["Authorization"] = "Bearer #{@token}"
+        req["Content-Type"] = "application/json"
+        body = Insika::Coercion.deep_stringify(state)
+        body["customer"] = customer if customer
+        req.body = JSON.generate(body)
+
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.read_timeout = @timeout
+        http.open_timeout = 10
+        res = http.start { http.request(req) }
+        code = res.code.to_i
+        return true if code.between?(200, 299)
+
+        message = begin
+          JSON.parse(res.body.to_s).dig("error", "message")
+        rescue JSON::ParserError
+          nil
+        end
+        raise SeedRefused, "HTTP 403#{" #{message}" if message}" if code == 403
+
+        raise Insika::Error, "HTTP #{code}#{" #{message}" if message}"
+      rescue SystemCallError, IOError, Net::OpenTimeout, Net::ReadTimeout => e
+        raise Insika::Error, e.class.to_s
+      end
+
       private
 
       def failure(msg, t0)
@@ -199,16 +279,18 @@ module Insika
 
       def turn(agent:, conv:, message:)
         t0 = mono
-        sub = @event_stream&.subscribe(types: [:tool_call])
+        sub = @event_stream&.subscribe(types: %i[tool_call ui])
         begin
           text = @runtime.chat(message, session_id: conv, agent: agent)
+          tools, ui = drain(sub)
           TurnOutcome.new(
-            result: TurnResult.new(output_text: text.to_s, tool_calls: drain_tools(sub), error: nil),
+            result: TurnResult.new(output_text: text.to_s, tool_calls: tools, ui: ui, error: nil),
             ttfb: nil, total: (mono - t0) * 1000.0, usage: nil
           )
         rescue Insika::Error => e
+          tools, ui = drain(sub)
           TurnOutcome.new(
-            result: TurnResult.new(output_text: "", tool_calls: drain_tools(sub), error: e.message),
+            result: TurnResult.new(output_text: "", tool_calls: tools, ui: ui, error: e.message),
             ttfb: nil, total: (mono - t0) * 1000.0, usage: nil
           )
         ensure
@@ -216,14 +298,34 @@ module Insika
         end
       end
 
+      # In-process seeding: the SAME `seed_session` command the HTTP route dispatches,
+      # on the graph's own bus — no route, no gate (there is no tenant token to
+      # protect here; whoever holds the graph already holds everything). A runtime
+      # that exposes no graph cannot seed, and says so as an error the Runner fails
+      # the case with.
+      def seed(conv, state, customer: nil)
+        bus = @runtime.graph.bus if @runtime.respond_to?(:graph) && @runtime.graph
+        raise Insika::Error, "transport cannot seed state: the runtime exposes no graph" if bus.nil?
+
+        payload = { id: conv, state: state }
+        payload[:customer] = customer if customer
+        bus.dispatch(Insika::Command.build(:seed_session, payload, transport: :internal))
+      end
+
       private
 
-      # The same shape an HTTP replay produces: [{ "name" =>, "status" => nil }]
-      # (the stream carries no per-tool status — that lives in the trace store).
-      def drain_tools(sub)
-        return [] if sub.nil?
+      # The same shapes an HTTP replay produces: tools as [{ "name" =>, "status" => nil }]
+      # (the stream carries no per-tool status — that lives in the trace store), ui as
+      # [{ "component" =>, "count" => }]. -> [tools, ui]
+      def drain(sub)
+        return [[], []] if sub.nil?
 
-        sub.drain_nonblocking.map { |ev| { "name" => ev.data[:name].to_s, "status" => nil } }
+        events = sub.drain_nonblocking
+        tools = events.select { |ev| ev.type == :tool_call }
+                      .map { |ev| { "name" => ev.data[:name].to_s, "status" => nil } }
+        ui = events.select { |ev| ev.type == :ui }
+                   .map { |ev| { "component" => ev.data[:component].to_s, "count" => ev.data[:count].to_i } }
+        [tools, ui]
       end
     end
 

data/lib/insika/evidence.rb

@@ -29,10 +29,12 @@ module Insika
     Spec = Data.define(:kind, :items_path, :attachments_path) do
       PATH_RE = /\A[a-zA-Z0-9_]+(?:\.[a-zA-Z0-9_]+)*\z/
 
-      # String | Hash | nil -> Spec | nil. Raises ValidationError on a blank kind
+      # String | Hash | Spec | nil -> Spec | nil. Raises ValidationError on a blank kind
       # or an empty/ill-formed path. All at ingestion, never at the turn.
       def self.parse(raw)
         return nil if raw.nil? || raw == false
+        # A data tool hands the envelope its definition's evidence — already a Spec.
+        return raw if raw.is_a?(Spec)
 
         h = raw.is_a?(String) ? { "kind" => raw } : Coercion.deep_stringify(raw)
         h = h.is_a?(Hash) ? h : {}
@@ -70,6 +72,13 @@ module Insika
     # model): [{ "type" => "card"|"image", "url" => String, "caption" => String|nil }].
     # Entries without a String url, or beyond MAX_ATTACHMENTS, are DROPPED — never
     # a turn failure (the card is a channel nicety, not the answer).
+    #
+    # Three OPTIONAL keys survive when present: `id` (the product the card stands
+    # for — what a presentation tool joins on), and `component`/`title` (stamped
+    # by a presentation call so the channel knows what it is rendering). Absent =
+    # absent; a card with none of them is byte-identical to before.
+    OPTIONAL_KEYS = %w[id component title].freeze
+
     def self.valid_attachments(list)
       Array(list).filter_map do |entry|
         next unless entry.is_a?(Hash)
@@ -78,9 +87,15 @@ module Insika
         next if url.empty?
 
         caption = Coercion.presence(entry["caption"] || entry[:caption])
-        { "type" => (entry["type"] || entry[:type]).to_s,
-          "url" => url[0, URL_MAX],
-          "caption" => caption }
+        caption &&= Coercion.utf8(caption)
+        card = { "type" => (entry["type"] || entry[:type]).to_s,
+                 "url" => url[0, URL_MAX],
+                 "caption" => caption }
+        OPTIONAL_KEYS.each do |k|
+          v = Coercion.presence(entry[k] || entry[k.to_sym])
+          card[k] = v.to_s if v
+        end
+        card
       end.first(MAX_ATTACHMENTS)
     end
 
@@ -106,11 +121,28 @@ module Insika
           items = SchemaGuard.dig(raw, spec.items_path) || []
           lean_items = items.first(MAX_ITEMS).map do |item|
             { "id" => (item["id"] || item[:id]).to_s,
+              # the line is what the model reads: truncated here; sanitized by the
+              # envelope's fence when the agent has `fencing` on (bytes as-is when off).
               "line" => Coercion.utf8((item["line"] || item[:line]).to_s)[0, LINE_MAX] }
           end
           lean = { "items" => lean_items }
-          attachments = Insika::Evidence.valid_attachments(SchemaGuard.dig(raw, spec.attachments_path))
-          [lean, attachments]
+          cards = stamp_ids(items, SchemaGuard.dig(raw, spec.attachments_path))
+          [lean, Insika::Evidence.valid_attachments(cards)]
+        end
+
+        # Items and attachments come from the SAME payload, one card per item in
+        # order — so a card that names no id of its own takes the id of the item at
+        # its position. That id is what a presentation tool later joins on. Stamped
+        # on the RAW list, before malformed cards are dropped: pairing after the
+        # drop would shift every later card onto the wrong product.
+        def stamp_ids(items, cards)
+          Array(cards).each_with_index.map do |card, i|
+            next card unless card.is_a?(Hash) && (card["id"] || card[:id]).nil?
+
+            item = items[i]
+            id = item.is_a?(Hash) ? (item["id"] || item[:id]).to_s : ""
+            id.empty? ? card : card.merge("id" => id)
+          end
         end
       end
     end
@@ -125,14 +157,26 @@ module Insika
     # Oldest-evicted cap: a session that outlives it needs a real cap or the row
     # grows forever.
     MAX_IDS = 1_000
+    # Cards kept per session, one per id, newest wins — enough for the last few
+    # searches, so "show me the second one" a turn later still has a card to show.
+    MAX_CARDS = 64
 
     def initialize(store: nil, session_id: nil)
       @store = store
       @session_id = session_id
       @ids = []
+      @cards = []
       @ungrounded = 0
     end
 
+    # -> one card per id (newest wins), capped. Shared by the ledger and the
+    # session store so both keep the same set.
+    def self.merge_cards(*lists)
+      lists.flatten.compact
+           .each_with_object({}) { |c, h| h[c["id"]] = c if c.is_a?(Hash) && c["id"] }
+           .values.last(MAX_CARDS)
+    end
+
     # The in-memory accumulator (the envelope appends, the validator/enforcer
     # read the union). The PERSISTED list is appended on flush (Executor, stage 8)
     # — the envelope never blocks on the store.
@@ -147,6 +191,19 @@ module Insika
       (session_ids + @ids).uniq.last(MAX_IDS)
     end
 
+    # The cards an evidence tool returned alongside its items, hoarded for the
+    # presentation tool. Only cards with an id are kept (nothing to join on
+    # otherwise). Persisted with the ids on flush.
+    def record_cards(cards)
+      @cards.concat(Array(cards).select { |c| c.is_a?(Hash) && c["id"] })
+      self
+    end
+
+    # -> the session's cards (persisted) + this turn's, one per id, newest wins.
+    def cards
+      self.class.merge_cards(session_evidence["cards"], @cards)
+    end
+
     attr_reader :ungrounded
 
     def ungrounded_count(claim)
@@ -161,9 +218,11 @@ module Insika
     def flush!
       return self unless @store && @session_id
 
-      @store.append_evidence(@session_id, ids: @ids, ungrounded: @ungrounded)
+      @store.append_evidence(@session_id, ids: @ids, ungrounded: @ungrounded, cards: @cards)
       @ids = []
+      @cards = []
       @ungrounded = 0
+      @session_evidence = nil
       self
     rescue Insika::Error
       self
@@ -172,12 +231,20 @@ module Insika
     private
 
     def session_ids
-      return [] unless @store && @session_id
+      Array(session_evidence["ids"]).map(&:to_s)
+    end
 
-      session = @store.find(@session_id)
-      Array(session&.evidence&.fetch("ids", [])).map(&:to_s)
-    rescue Insika::NotFoundError
-      []
+    # Read ONCE per ledger (= per turn): a batch of gated calls must not re-read
+    # the session row for each. `flush!` forgets it, so the next read sees what
+    # it just appended.
+    def session_evidence
+      return {} unless @store && @session_id
+
+      @session_evidence ||= begin
+        @store.find(@session_id)&.evidence || {}
+      rescue Insika::NotFoundError
+        {}
+      end
     end
   end
 end

data/lib/insika/executor.rb

@@ -913,6 +913,7 @@ module Insika
       stamp_customer_session(task, profile)
       state.turn_context = build_turn_context(task, profile, state) # data-tools' ctx.*
       state.resumed = !resume_from.nil? # EdgeLimiter: an admitted turn is never re-counted
+      state.fence_max_chars = fence_max_chars if Insika::Fence.enabled?(profile)
       # resolved for the RUN, not per message, so what the turn accepts cannot
       # change under it. Same cost as the EdgeLimiter's per-turn resolution. Only for a
       # SESSION turn: steering needs a session to arrive through, and resolving here for a
@@ -1969,19 +1970,8 @@ module Insika
     # indistinguishable from a single-tenant customer ref, and the Studio drill
     # must not list conversations as customers with a Forget button.
     def memory_tenant(task)
-      customer = command_customer(task)
-      return command_tenant(task) || session_scope(task.session_id) if customer.nil?
-
-      [command_tenant(task), customer].compact.join(":")
-    end
-
-    # The marked per-session scope : "chat:<session id>" -> cell
-    # "memory:chat:<session id>". nil for a one-shot turn (no session) — the
-    # MemoryStore applies _default.
-    def session_scope(session_id)
-      return nil if session_id.nil?
-
-      "#{MemoryStore::SESSION_TAG}:#{session_id}"
+      MemoryStore.scope_for(tenant: command_tenant(task), customer: command_customer(task),
+                            session_id: task.session_id)
     end
 
     # WS8 +  : stamp the customer (WS8 — the `forget_customer`
@@ -2515,7 +2505,11 @@ module Insika
 
       # the hoarded evidence attachments ride the channel delivery
       # (additive outbox payload key — the channel contract widens, nothing breaks).
-      attachments = state.respond_to?(:evidence_attachments) ? state.evidence_attachments : nil
+      # When the model SELECTED cards with a presentation tool this turn, the
+      # selection is what rides — in call order, each card stamped with the
+      # component and title of the call that picked it. No selection = every
+      # hoarded card, as before.
+      attachments = delivery_attachments(state)
       deliveries = @channel_delivery.record_balloons(
         task: task, channel_id: channel_id, content: content,
         progressive: @channel_delivery.progressive?(channel_id),
@@ -2529,6 +2523,17 @@ module Insika
       nil
     end
 
+    def delivery_attachments(state)
+      presentations = state.respond_to?(:presentations) ? Array(state.presentations) : []
+      if presentations.empty?
+        return state.respond_to?(:evidence_attachments) ? state.evidence_attachments : nil
+      end
+
+      presentations.flat_map do |p|
+        Array(p["items"]).map { |item| item.merge("component" => p["component"], "title" => p["title"]).compact }
+      end
+    end
+
     # Turns whose combined transcript slice is this trivially short skip
     # extraction entirely ("ok thanks" exchanges) — no new config surface,
     # just avoids a wasted utility-model call.
@@ -2602,15 +2607,9 @@ module Insika
       PROMPT
     end
 
-    # Redacted (RFC's PII rule applies to what reaches the model too, not
-    # just what gets persisted).
-    def knowledge_transcript(new_messages)
-      redacted, = Insika::Safety::Detectors.redact(
-        new_messages.each_with_index.map { |m, i| "[#{i}] #{m['role'] || m[:role]}: #{m['content'] || m[:content]}" }
-                    .join("\n")
-      )
-      redacted
-    end
+    # Only what people said, PII-redacted — a `role: tool` message is
+    # third-party text and never a source of a learned concept.
+    def knowledge_transcript(new_messages) = Insika::SpokenTranscript.render(new_messages)
 
     def utility_model
       return nil unless @settings_store
@@ -2618,6 +2617,14 @@ module Insika
       @settings_store.get["utility_model"]
     end
 
+    # `Settings fencing.max_chars`, the per-leaf cap the envelope applies for a
+    # fenced agent. One settings read per fenced turn, like the queue policy.
+    def fence_max_chars
+      config = @settings_store && Coercion.deep_stringify(@settings_store.get["fencing"])
+      n = config && config["max_chars"].to_i
+      n && n.positive? ? n : Insika::Fence::DEFAULT_MAX_CHARS
+    end
+
     # in-session compaction (RFC-0044). Platform-gated
     # (Settings compaction.enabled — parity when off), planned over the
     # POST-append transcript (persist_turn already wrote this turn's messages),

data/lib/insika/fence.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Insika
+  # Third-party text — a product description, a review, an FAQ body, a fact a
+  # customer dictated — reaches the model as bytes, and the model reads every
+  # one of them. Those bytes can carry zero-width characters, bidi overrides, a
+  # forged "\n\nassistant:" turn marker or a tag shaped like the engine's own
+  # transcript markup. This is the ONE sanitizer for that class of input:
+  # pure Ruby, stdlib only, no IO, every pattern bounded so a hostile megabyte
+  # finishes in linear time on the reactor.
+  #
+  # It never re-wraps. The engine already renders data inside fixed labels
+  # (<memory>, <knowledge>, a tool result) and the FenceNotice provider names
+  # them to the model; what this module does is make sure the DATA cannot
+  # reproduce those labels or a turn boundary.
+  module Fence
+    module_function
+
+    # Zero-width, bidi and format controls: the usual carriers of hidden text.
+    INVISIBLE = /[\u00AD\u061C\u180E\u200B-\u200F\u2028-\u202E\u2060-\u2064\u2066-\u2069\u206A-\u206F\uFE00-\uFE0F\uFEFF\uFFF9-\uFFFB\u{E0000}-\u{E007F}\u{E0100}-\u{E01EF}]/
+
+    # C0/C1 controls except tab, newline and carriage return.
+    CONTROL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/
+
+    # Tag names that read as transcript or tool-call markup to a model, plus the
+    # labels the engine itself renders around data. A copy of any of them inside
+    # DATA is a forgery — `<fact>` inside a fact value would end the fact early.
+    TAG_NAMES = %w[
+      system human user assistant transcript conversation
+      tool_result tool_use function_calls function_results invoke
+      memory knowledge fact note concept briefing conversation_summary request_context
+    ].freeze
+
+    # Only tag-SHAPED text: bare (`<system>`), closing (`</memory>`), self-closing,
+    # optionally namespaced (`<ns:invoke>`), with at most eight `name="value"`
+    # attributes. Bare words are not attributes, so `<system requirements>`
+    # passes. Quantifiers are bounded and non-adjacent — linear on unclosed input.
+    TAG_ATTRS = /(?:[ \t]+[\w:.-]{1,40}[ \t]*=[ \t]*(?:"[^"]{0,200}"|'[^']{0,200}'|[^\s"'>]{1,200})){0,8}/
+    TAG = /<[ \t]*\/?[ \t]*(?:[a-z][\w.-]{0,30}:)?(?:#{TAG_NAMES.join('|')})\b#{TAG_ATTRS.source}[ \t]*\/?>/i
+
+    # Provider special tokens (`<|im_start|>`, `<|endoftext|>`).
+    SPECIAL_TOKEN = /<\|[^|<>\r\n]{1,64}\|>/
+
+    # A forged turn boundary: a blank line (or the very start), a full role word,
+    # a colon. A mid-sentence "user:" and a one-letter list marker ("A:") do not
+    # match. The colon becomes " -", so the words survive as prose.
+    TURN_MARKER = /(\A[ \t]*|(?:\r\n|\r|\n)[ \t]*(?:\r\n|\r|\n)[ \t]*)(human|assistant|system|user)[ \t]*:/i
+
+    REMOVED = "[removed]"
+    TRUNCATED = " …[truncated]"
+    # One string leaf after the envelope; `Settings fencing.max_chars` overrides.
+    DEFAULT_MAX_CHARS = 12_000
+
+    # -> String. `max_chars` bounds the result INCLUDING the suffix.
+    def sanitize_text(text, max_chars: nil)
+      s = Coercion.utf8(text).unicode_normalize(:nfkc)
+      s = s.gsub(INVISIBLE, "").gsub(CONTROL, " ")
+      # To a fixpoint: a tag nested inside another (`</memory</memory>>`) must
+      # not reassemble once the inner one goes. Each round shrinks the string or
+      # stops, so the loop is bounded by the number of tags.
+      loop do
+        stripped = s.gsub(TAG, REMOVED).gsub(SPECIAL_TOKEN, REMOVED)
+        break if stripped == s
+
+        s = stripped
+      end
+      s = s.gsub(TURN_MARKER) { "#{Regexp.last_match(1)}#{Regexp.last_match(2)} -" }
+      cap(s, max_chars)
+    end
+
+    # Walks Hash/Array leaves; String leaves are sanitized, keys and every other
+    # type pass through untouched (numbers, booleans, nil are not text).
+    def sanitize_value(obj, max_chars: nil)
+      case obj
+      when String then sanitize_text(obj, max_chars: max_chars)
+      when Hash then obj.transform_values { |v| sanitize_value(v, max_chars: max_chars) }
+      when Array then obj.map { |v| sanitize_value(v, max_chars: max_chars) }
+      else obj
+      end
+    end
+
+    # The per-agent switch, read the same way everywhere (envelope, providers,
+    # doctor): an operator's `fencing true`, a form's "1" or a JSON `true`.
+    def enabled?(profile)
+      profile.respond_to?(:fencing) && Coercion.truthy?(profile.fencing)
+    end
+
+    def cap(text, max_chars)
+      return text if max_chars.nil? || text.length <= max_chars
+      return text[0, max_chars] if max_chars <= TRUNCATED.length
+
+      text[0, max_chars - TRUNCATED.length] + TRUNCATED
+    end
+    private_class_method :cap
+  end
+end

data/lib/insika/golden_store.rb

@@ -148,6 +148,9 @@ module Insika
       # when present. A case that lost its reference in a round-trip would stop being
       # compared against the incumbent and the report would look identical.
       h["reference"] = golden.reference unless golden.reference.empty?
+      # And `state`: a snapshot case that lost its snapshot would replay from an
+      # empty conversation and fail for a reason that has nothing to do with the agent.
+      h["state"] = golden.state unless golden.state.empty?
       # `tenant` follows the same omit-when-default rule: "platform" is the
       # loader's own default, so leaving it out reproduces the same case; an
       # explicit tenant is a case's isolation boundary and must never round-trip away.

data/lib/insika/mcp_store.rb

@@ -135,7 +135,7 @@ module Insika
 
     def http_like?(transport) = %w[http sse].include?(transport.to_s)
 
-    # -> [{"name","description","inputSchema"}] string-keyed, dropping any
+    # -> [{"name","description","inputSchema"[,"annotations"]}] string-keyed, dropping any
     # entry without a name (nothing to register a Registry::Entry under).
     def normalize_tools_cache(tools)
       Array(tools).filter_map do |t|
@@ -143,7 +143,10 @@ module Insika
         name = presence(h["name"])
         next nil if name.nil?
 
-        { "name" => name, "description" => h["description"].to_s, "inputSchema" => h["inputSchema"] || {} }
+        cached = { "name" => name, "description" => h["description"].to_s, "inputSchema" => h["inputSchema"] || {} }
+        # the server's own hints (readOnlyHint decides side_effect at registration)
+        cached["annotations"] = h["annotations"] if h["annotations"].is_a?(Hash)
+        cached
       end
     end
 

data/lib/insika/mcp_tool_registry.rb

@@ -71,11 +71,18 @@ module Insika
       instance = record["name"]
       Insika::Registry::Entry.new(
         name: tool["name"], plugin: "mcp:#{instance}",
-        metadata: { optional: false, side_effect: true, group: "mcp:#{instance}", tags: [] },
+        metadata: { optional: false, side_effect: !read_only?(tool), group: "mcp:#{instance}", tags: [] },
         factory: -> { build_tool(record, tool) }
       )
     end
 
+    # An MCP tool is a side effect unless its server says otherwise
+    # (`annotations.readOnlyHint`): a write is never re-run on resume and runs
+    # serially within the session; a declared read keeps `tool_concurrency`.
+    def read_only?(tool)
+      Coercion.truthy?(tool.dig("annotations", "readOnlyHint"))
+    end
+
     # Lazy require (McpLiveTool < RubyLLM::Tool pulls in ruby_llm) — kept out
     # of insika.rb load-time, loaded on the 1st instance (turn time), same
     # discipline as OverlayToolRegistry#build_tool for data-tools.

data/lib/insika/memory_store.rb

@@ -42,6 +42,18 @@ module Insika
     # ids live in a different namespace in practice.
     SESSION_TAG = "chat"
 
+    # The ONE memory-cell rule, read by the turn (Executor) and by whoever
+    # writes a cell the turn must find (SeedSession): a customer -> the
+    # "[tenant:]customer" cell; otherwise the tenant's cell; otherwise the marked
+    # per-session cell "chat:<session id>" (nil for a one-shot turn with no
+    # session — the store applies _default).
+    def self.scope_for(tenant:, customer:, session_id:)
+      return [tenant, customer].compact.join(":") if customer
+      return tenant if tenant
+
+      "#{SESSION_TAG}:#{session_id}" if session_id
+    end
+
     Fact = Data.define(:key, :value, :origin, :created_at, :updated_at, :expires_at)
     Note = Data.define(:id, :text, :created_at)
 

data/lib/insika/overlay_tool_registry.rb

@@ -112,6 +112,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,