insika 0.7.0 → 0.9.0

data/lib/insika/loop_detector.rb

@@ -50,9 +50,7 @@ module Insika
       @streak = 0
       @intervened = false  # the ONE warning of this turn has been delivered
       @pending = false     # detection fired; waiting for the batch boundary
-      @expected = nil      # tool calls announced by the batch in flight
-      @seen = 0
-      @halted = false
+      @batch = ToolBatch.new
     end
 
     # From ChatBuilder's before_tool_call. Raises BEFORE the call executes once
@@ -80,41 +78,21 @@ module Insika
 
     # From ChatBuilder's after_tool_result, with the RAW result — the only place
     # a Tool::Halt is still recognizable (SteerInjector's comment applies here).
-    def tool_result(result)
-      @halted = true if defined?(RubyLLM::Tool::Halt) && result.is_a?(RubyLLM::Tool::Halt)
-    end
+    def tool_result(result) = @batch.halt!(result)
 
     # RubyLLM after_message. An assistant message carrying tool calls OPENS a
     # batch; the Nth tool result CLOSES it — the one boundary where appending
-    # is valid.
+    # is valid (ToolBatch owns that arithmetic; TurnBudget follows the same rule).
     def message_ended(message)
-      role = field(message, :role).to_s
-      return open_batch(message) if role == "assistant"
-      return unless role == "tool" && @expected
-
-      @seen += 1
-      intervene! if @seen >= @expected
+      intervene! if @batch.closed?(message)
     end
 
     private
 
-    def open_batch(message)
-      calls = field(message, :tool_calls)
-      size = calls.respond_to?(:size) ? calls.size : 0
-      # No tool call = the model talking; the turn is ending and a pending
-      # warning is moot — the loop resolved itself.
-      return @expected = nil if size.zero?
-
-      @expected = size
-      @seen = 0
-      @halted = false
-    end
-
     def intervene!
-      @expected = nil
       return unless @pending
       @pending = false
-      return if @halted # nothing will read it (halt_when): drop, never deliver
+      return if @batch.halted? # nothing will read it (halt_when): drop, never deliver
 
       @intervened = true
       name, = @last
@@ -132,12 +110,5 @@ module Insika
       else value
       end
     end
-
-    def field(message, name)
-      return message.public_send(name) if message.respond_to?(name)
-      return message[name] || message[name.to_s] if message.respond_to?(:[])
-
-      nil
-    end
   end
 end

data/lib/insika/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,

data/lib/insika/prefix_fingerprint.rb

@@ -9,47 +9,52 @@ module Insika
   # (name + description + parameters.inspect, executor.rb:957). Outputs are
   # PII-free digests: it never sees message text, only hashes leave this class.
   # Pure stdlib (digest/sha2), no gem, no IO.
+  #
+  # The chain follows the cache boundary: the cumulative "prefix" is over the
+  # IDENTITY categories + tool_schemas only — the bytes the cache breakpoint
+  # actually covers. Volatile categories (memory, knowledge, briefing, request)
+  # render below the breakpoint, so a change there is not a prefix invalidation;
+  # they still get their own digest (the trace shows them) but sit AFTER the
+  # "prefix" key, outside the chain.
   class PrefixFingerprint
     # -> { "prompt" => "sha256…", …, "tool_schemas" => "sha256…",
-    #      "prefix" => "sha256…" }
-    # Keys are the demodulized, downcased provider ids, in render order.
+    #      "prefix" => "sha256…", "memory" => "sha256…", … }
+    # Keys are the demodulized, downcased provider ids. Order: identity
+    # categories (render order), "tool_schemas", "prefix", then the volatile
+    # categories — everything before "prefix" is the chain.
     # A category with no fragments is absent (not an empty hash).
     # The category digest = SHA256 of the category's fragments joined "\n\n"
     # (the Builder's separator — the digest matches rendered bytes).
-    # "prefix" = SHA256 of the category digests concatenated IN CHAIN ORDER
-    # (identity categories, then volatile, then tool_schemas) — any divergence
-    # anywhere above the boundary changes it.
+    # "prefix" = SHA256 of the chain digests concatenated in order — any
+    # divergence anywhere above the boundary changes it. A fragment with no
+    # layer stamp reads as volatile, like everywhere else.
     def self.compute(system_fragments, tool_serial:)
-      digests = {} # category name -> digest, insertion = render order
-      grouped = system_fragments.group_by { |f| category(f.source) }
-      grouped.each do |name, frags|
-        digests[name] = digest(frags.map(&:content).join("\n\n"))
-      end
+      identity, volatile = system_fragments.partition { |f| (f.layer || :volatile) == :identity }
+      digests = category_digests(identity)
       digests["tool_schemas"] = digest(tool_serial.to_s) unless tool_serial.nil?
       digests["prefix"] = digest(digests.values.join) unless digests.empty?
-      digests
+      digests.merge(category_digests(volatile))
     end
 
-    # -> String | nil. The first category (in CURRENT chain order) whose digest
-    # differs or is absent from `previous`; else the first PREVIOUS key now
-    # absent from the current chain (a vanished block is a divergence too);
-    # else nil. nil `previous` (first turn) -> nil. The returned name is a
-    # category id — PII-free by construction.
-    #
-    # The cumulative "prefix" key is deliberately SKIPPED in the scan: its
-    # digest changes whenever ANY category moves, so scanning it would shadow a
-    # vanished block (every surviving category matches, "prefix" differs, and
-    # the vanished-fallback below becomes unreachable — reporting `broke:
-    # prefix` instead of the category that actually left).
+    # -> String | nil. nil when the cumulative "prefix" did not move (a
+    # volatile change is not an invalidation). Else the first chain category
+    # (in CURRENT chain order) whose digest differs or is absent from
+    # `previous`; else the first PREVIOUS chain key now absent from the current
+    # chain (a vanished block is a divergence too). nil `previous` (first turn)
+    # -> nil. The returned name is a category id — PII-free by construction.
     def self.invalidation_reason(current, previous)
       return nil unless previous.is_a?(Hash)
+      return nil if current["prefix"] == previous["prefix"]
 
-      current.each_key do |name|
-        next if name == "prefix"
+      chain(current).find { |name| previous[name] != current[name] } ||
+        (chain(previous) - current.keys).first
+    end
+
+    def self.chain(map) = map.keys.take_while { |k| k != "prefix" }
 
-        return name unless previous[name] == current[name]
-      end
-      (previous.keys - current.keys).first
+    def self.category_digests(fragments)
+      fragments.group_by { |f| category(f.source) }
+               .transform_values { |frags| digest(frags.map(&:content).join("\n\n")) }
     end
 
     def self.category(source) = source.to_s.split("::").last.to_s.downcase

data/lib/insika/profile_source.rb

@@ -74,6 +74,13 @@ module Insika
 
     def delete(id) = @cs.delete(SCOPE, id.to_s)
 
+    # The STORED records, unbuilt (string keys, straight off the JSON
+    # round-trip). `all` runs every record through AgentProfile.build, which
+    # normalizes — and repairs — what it reads, so a caller that needs to judge
+    # the truth ON DISK (the doctor) cannot use it: a repaired-on-read profile
+    # is indistinguishable there from a well-formed record.
+    def all_raw = @cs.all(SCOPE)
+
     private
 
     # Rebuilds the AgentProfile from the record (the JSON round-trip turns symbols
@@ -108,6 +115,7 @@ module Insika
         # only a stored explicit false turns the discipline block off.
         tool_persistence: h[:tool_persistence],
         tool_output_compression: h[:tool_output_compression],
+        fencing: h[:fencing],
         # params/model_policy: the resolver tolerates string keys from
         # the JSON round-trip (ModelResolver#normalize_params / ModelPolicy), so no
         # re-symbolization needed here.

data/lib/insika/server/app.rb

@@ -56,8 +56,13 @@ module Insika
                      config:, pending_action_store: nil, a2a: nil, provisioner: nil,
                      workflow_registry: nil, onboarding: nil, profiles: nil,
                      channels: nil, logger: nil, token_store: nil, outcome_store: nil,
-                     executor: nil, db_path: nil, tool_registry: nil, mcp_store: nil)
+                     executor: nil, db_path: nil, tool_registry: nil, mcp_store: nil,
+                     settings_store: nil)
         @command_bus = command_bus
+        # READ for one gate: `POST /v1/conversations/:id/seed` answers only while
+        # the platform setting `evals.seeding` is on. nil = no settings = seeding
+        # off (fail-closed — the base wiring has no SettingsStore and cannot seed).
+        @settings_store = settings_store
         @event_stream = event_stream
         @session_store = session_store
         @task_store = task_store
@@ -132,6 +137,8 @@ module Insika
         error_response(422, e)
       rescue Insika::NotFoundError => e
         error_response(404, e)
+      rescue Insika::ConflictError => e
+        error_response(409, e) # the write contradicts existing state (a seed on a used conversation)
       rescue Async::TimeoutError => e
         error_response(504, e) # synchronous control request exceeded the ceiling
       rescue StandardError => e
@@ -186,6 +193,8 @@ module Insika
           handle_trigger_workflow(req, name)
         in ["POST", ["v1", "responses"]]
           handle_responses(req)
+        in ["POST", ["v1", "conversations", id, "seed"]]
+          handle_seed(req, id)
         in ["POST", ["v1", "outcomes"]] if @outcome_store
           handle_record_outcome(req)
         in ["GET", ["v1", "outcomes"]] if @outcome_store
@@ -427,6 +436,38 @@ module Insika
                               tenant: tenant)
       end
 
+      # POST /v1/conversations/:id/seed — loads the snapshot an eval case starts from
+      # (its `state:` — evidence ids, memory facts/notes, history, briefing fields)
+      # into the conversation BEFORE its first turn. Body = the state mapping, plus an
+      # optional `customer` (the memory scope the turns will carry). Same Bearer as
+      # /v1/responses and the same id namespacing for a tenant, so the seeded session
+      # IS the one the turn continues. 200 {session}; 409 when the conversation
+      # already has messages (seeding a used one is a test bug, not a merge).
+      #
+      # Refused (auth error) unless the platform setting `evals.seeding` is on. A seeded
+      # conversation is a fabricated precondition written under the tenant token:
+      # right on the machine running snapshot evals, wrong in production — so the
+      # default is off and the doctor warns while it is on.
+      def handle_seed(req, id)
+        return auth_error(403, "seeding is off (settings evals.seeding)") unless seeding_enabled?
+
+        body = parse_body(req)
+        tenant = req_tenant(req)
+        # the conversation id as the TURN will send it in `user` — the path
+        # segment arrives percent-encoded (the eval transport encodes "loja:c1").
+        conv = URI.decode_www_form_component(id)
+        payload = { id: scoped_session_id(tenant, conv), state: body.except(:customer) }
+        (customer = Insika::Coercion.presence(body[:customer])) && (payload[:customer] = customer)
+        command = Insika::Command.build(:seed_session, payload, transport: :http, tenant: tenant)
+        session = dispatch_with_timeout(command)
+        json_response(200, { session: session.to_h })
+      end
+
+      def seeding_enabled?
+        settings = @settings_store&.get
+        settings.is_a?(Hash) && (settings["evals"] || {})["seeding"] == true
+      end
+
       # POST /v1/agents — provisions (upserts) an agent from a standardized
       # PACK. Same Bearer as /v1/responses (gateway_token,
       # fail-closed). The consumer (GatewayClient/ProvisionStore) sends the pack as
@@ -625,6 +666,7 @@ TENANT_SURFACES = [
         ["POST", ["v1", "sessions"]],
         ["POST", ["v1", "messages"]],
         ["POST", ["v1", "responses"]],
+        ["POST", ["v1", "conversations", nil, "seed"]],
         ["POST", ["v1", "outcomes"]],
         ["GET", ["v1", "outcomes"]],
         ["POST", ["v1", "workflows", nil]],

data/lib/insika/server/rack_app.rb

@@ -80,6 +80,8 @@ module Insika
           outcome_store: @graph.outcome_store,
           # GET/PUT/DELETE /v1/mcp[/:name] — the config surface.
           mcp_store: @rt.component(:mcp_store),
+          # POST /v1/conversations/:id/seed answers only while `evals.seeding` is on.
+          settings_store: @rt.component(:settings_store),
           # a 500's error_ref must be findable in the process log.
           logger: $stdout
         )

data/lib/insika/server/responses.rb

@@ -12,9 +12,9 @@ module Insika
     # OpenAI Responses SSE frame (or nil for events with no counterpart). Follows the
     # constitutional rule: no business logic, no store access here.
     #
-    # Request: { model: "openclaw:<agent>", user: "<chat.id>", stream: true,
+    # Request: { model: "insika:<agent>", user: "<chat.id>", stream: true,
     #            input: "<string with already-composed blocks>" } + header
-    # X-Openclaw-Agent (agent fallback). The `input` enters VERBATIM as the
+    # X-Insika-Agent (agent fallback). The `input` enters VERBATIM as the
     # turn's message — the blocks (<memoria>/<dados_conhecidos>/directives) already come
     # composed by the consumer (the engine does not interpret them).
     module Responses
@@ -32,8 +32,8 @@ module Insika
       # gets that filtered structurally instead of by a regex on the leading tag.
       # Omitted = a customer typed it, which is what every turn meant before.
       def parse_request(body, req)
-        agent = body[:model].to_s.sub(/\Aopenclaw:/, "")
-        agent = req.get_header("HTTP_X_OPENCLAW_AGENT").to_s if agent.empty?
+        agent = body[:model].to_s.sub(/\Ainsika:/, "")
+        agent = req.get_header("HTTP_X_INSIKA_AGENT").to_s if agent.empty?
         raise Insika::ValidationError, "model/agent missing" if agent.strip.empty?
 
         user = body[:user].to_s
@@ -95,7 +95,7 @@ module Insika
       end
 
       # Turn Event -> OpenAI Responses SSE frame | nil (event with no
-      # counterpart: :task_started, :tool_result, :skill_activated, ...).
+      # counterpart: :task_started, :skill_activated, ...).
       # Terminal events emit the final frame + `[DONE]` (close the stream).
       def frame_for(event)
         case event.type
@@ -103,9 +103,27 @@ module Insika
           sse("response.output_text.delta",
               { type: "response.output_text.delta", delta: event.data[:delta].to_s })
         when :tool_call
-          sse("response.output_item.added",
-              { type: "response.output_item.added",
-                item: { type: "function_call", name: event.data[:name].to_s } })
+          item = { type: "function_call", name: event.data[:name].to_s }
+          # The provider's call id, as the OpenAI item carries it: `added` and `done`
+          # are TWO frames of ONE call, and a consumer pairs them by this. Absent when
+          # the emitter had none.
+          (id = event.data[:call_id]) && (item[:call_id] = id.to_s)
+          # The call's arguments, as the OpenAI item carries them (a JSON string).
+          # Absent when the emitter had none to report.
+          (args = event.data[:arguments]) && (item[:arguments] = args.is_a?(String) ? args : JSON.generate(args))
+          sse("response.output_item.added", { type: "response.output_item.added", item: item })
+        when :tool_result
+          # How the call ENDED — ok / error / blocked (+ the gate that held it). Until
+          # this frame the stream carried tool NAMES only, so nothing outside the
+          # process could tell "the tool ran" from "a gate refused it" or "it errored".
+          # The result body itself stays inside: it is the model's input, not the
+          # consumer's answer. Same `call_id` as the `added` frame — a consumer that
+          # counts calls counts `added`, not both.
+          item = { type: "function_call", name: event.data[:name].to_s,
+                   status: (event.data[:status] || "ok").to_s }
+          (id = event.data[:call_id]) && (item[:call_id] = id.to_s)
+          (gate = event.data[:gate]) && (item[:gate] = gate.to_s)
+          sse("response.output_item.done", { type: "response.output_item.done", item: item })
         when :task_completed
           completed(event) + done
         when :task_failed
@@ -149,6 +167,15 @@ module Insika
           # Studio + the trace. Explicit (not a fall-through) to keep the closed
           # catalog honest.
           nil
+        when :ui
+          # A presentation tool's selection: what the customer should SEE alongside
+          # the answer. Namespaced like `insika.intermediate` — no OpenAI Responses
+          # counterpart, unknown to strict clients, safely ignored. `items` are the
+          # cards the engine validated and joined (id/url/caption); `dropped` is what
+          # the model asked for and could not be shown, with the reason.
+          sse("insika.ui", { type: "insika.ui", component: event.data[:component].to_s,
+                             title: event.data[:title], items: Array(event.data[:items]),
+                             count: event.data[:count].to_i, dropped: Array(event.data[:dropped]) })
         when :ttft
           # the live TTFB signal (WS6, INSIKA_TURN_TIMING opt-in): the provider's
           # ms-to-first-token, emitted when the first content chunk arrives.

data/lib/insika/session_store.rb

@@ -23,11 +23,11 @@ module Insika
     KEY_PREFIX = "session:"
 
     Session = Data.define(:id, :messages, :vars, :memory_refs,
-                          :created_at, :updated_at, :briefing, :evidence) do
+                          :created_at, :updated_at, :briefing, :evidence, :compaction) do
       # Trailing members with defaults: an old record without the "briefing" /
-      # "evidence" keys reads as empty/nil without a migration.
+      # "evidence" / "compaction" keys reads as empty/nil without a migration.
       def initialize(id:, messages:, vars:, memory_refs:, created_at:, updated_at:,
-                     briefing: nil, evidence: nil)
+                     briefing: nil, evidence: nil, compaction: nil)
         super
       end
     end
@@ -101,12 +101,15 @@ module Insika
     # appends this turn's evidence (ids + ungrounded delta) to the
     # session record. RMW like append_messages — the SessionActor serializes
     # same-session turns; the copy is in the method comment.
-    def append_evidence(id, ids:, ungrounded:)
+    def append_evidence(id, ids:, ungrounded:, cards: [])
       record = fetch!(id)
       ev = record["evidence"] ||= { "ids" => [], "ungrounded" => 0 }
       fresh = (ev["ids"] + Array(ids).map(&:to_s).reject(&:empty?)).uniq.last(EvidenceLedger::MAX_IDS)
       ev["ids"] = fresh
       ev["ungrounded"] = ev["ungrounded"].to_i + ungrounded.to_i
+      # the cards those ids came with (one per id, newest wins) — what a
+      # presentation tool joins on in a LATER turn. Absent until a card arrives.
+      ev["cards"] = EvidenceLedger.merge_cards(ev["cards"], cards) unless Array(cards).empty?
       record["updated_at"] = timestamp
       @store.set(SCOPE, key_for(id), record)
       to_session(record)
@@ -150,6 +153,35 @@ module Insika
       to_session(record)
     end
 
+    # -> Session. Persists the in-session compaction state (RFC-0044): the
+    # summary of messages[0...upto] plus the boundary. `upto` is MONOTONIC —
+    # a write that does not move the boundary forward is a no-op (a stale
+    # double-write from a racing worker can never move it backwards). `runs`
+    # counts compactions over the session's lifetime (the trace reports it).
+    #
+    # CONCURRENCY NOTE: an unlocked RMW (read -> mutate -> set), like
+    # update_briefing — and safe for the same reason: nothing in the
+    # read/mutate/set path suspends, so no other writer can interleave
+    # mid-RMW. The LLM call that produced the summary happened BEFORE this
+    # method; only the plain write lives here.
+    def set_compaction(id, summary:, upto:, model: nil)
+      record = fetch!(id)
+      current = record["compaction"]
+      upto = Integer(upto)
+      return to_session(record) if current && upto <= current["upto"].to_i
+
+      record["compaction"] = {
+        "summary" => Coercion.utf8(summary.to_s),
+        "upto" => upto,
+        "runs" => (current ? current["runs"].to_i : 0) + 1,
+        "model" => Coercion.presence(model.to_s),
+        "at" => timestamp
+      }.compact
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_session(record)
+    end
+
     # -> bool (delegates to the backend: false for a nonexistent id)
     def delete(id)
       @store.delete(SCOPE, key_for(id))
@@ -189,7 +221,8 @@ module Insika
         created_at: record["created_at"],
         updated_at: record["updated_at"],
         briefing: record["briefing"] || { "fields" => {}, "next_step" => nil },
-        evidence: record["evidence"]
+        evidence: record["evidence"],
+        compaction: record["compaction"]
       )
     end
 

data/lib/insika/settings_store.rb

@@ -30,7 +30,18 @@ module Insika
       "max_retries" => 2,
       "turn_timeout" => 120,
       "tool_timeout" => 30,
-      "compaction" => { "enabled" => false, "keep_last" => 20 },
+      # In-session compaction (RFC-0044): when a session's UNCOMPACTED
+      # transcript grows past `compact_after` messages, everything but the
+      # last `keep_last` is summarized (model -> compaction.model, else the
+      # platform utility_model) into one history fragment. `prompt` replaces
+      # the engine default wholesale (the distill convention). enabled: false
+      # = parity (nothing runs). Additive keys — reads overlay DEFAULTS.
+      "compaction" => { "enabled" => false, "keep_last" => 20,
+                        "compact_after" => 40, "model" => nil },
+      # Fencing (per-agent `fencing` flag): the cap on ONE string leaf of a tool
+      # result after sanitizing. Platform-wide — the leaf size is a context-budget
+      # concern, not a persona one. Additive key — reads overlay DEFAULTS.
+      "fencing" => { "max_chars" => 12_000 },
       # Data lifecycle (WS8, phase 2): the RETENTION window in days. The
       # tick's Retention sweep purges sessions (+traces), terminal tasks
       # (+checkpoints), memory cells and outcomes older than this. nil/0 =
@@ -74,7 +85,12 @@ module Insika
         "aggregate" => "median",
         "min_agreement" => 0.5,
         "quorum" => 1,
-        "tolerance" => 0.05
+        "tolerance" => 0.05,
+        # seeding -> opens POST /v1/conversations/:id/seed, the route a snapshot eval
+        #            loads a case's `state:` through. OFF by default: a seeded
+        #            conversation is a fabricated precondition, and production must
+        #            not accept one under the tenant token. The doctor warns when on.
+        "seeding" => false
       },
       # Edge limits — the platform layer of the EdgeLimiter.
       # nil/0 = off (opt-in). chat_rate_limit = turn attempts per chat per

data/lib/insika/soak/runner.rb

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

data/lib/insika/spoken_transcript.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Insika
+  # The transcript slice an EXTRACTOR reads — memory distillation, knowledge
+  # extraction. Only what people said: `user` and `assistant` prose. A
+  # `role: tool` message is a product description, a search result, an FAQ body
+  # — third-party text; a customer fact or a learned concept distilled from it
+  # is a defect, not a behaviour to preserve. Tool-call payloads never render
+  # either (only `content` does). Indices are the ORIGINAL message positions,
+  # so a proposal's `turns` still point at the right message.
+  module SpokenTranscript
+    module_function
+
+    ROLES = %w[user assistant].freeze
+
+    # -> String, PII-redacted (what reaches the utility model follows the same
+    # redaction rule as what gets persisted). Messages are store records: string
+    # keys, like everything at the persistence boundary.
+    def render(messages)
+      lines = Array(messages).each_with_index.filter_map do |m, i|
+        role = m["role"].to_s
+        content = m["content"].to_s
+        next unless ROLES.include?(role) && !content.strip.empty?
+
+        "[#{i}] #{role}: #{content}"
+      end
+      redacted, = Insika::Safety::Detectors.redact(lines.join("\n"))
+      redacted
+    end
+  end
+end