insika 0.7.0 → 0.9.0

data/docs/prompts/ADD-TOOL.md

@@ -30,6 +30,7 @@ with one turn. Nothing more.
 | The need | The kind | Where it lives |
 |---|---|---|
 | Call an external HTTP API | **data tool** (`data_tool` in the DSL block) | a row in SQLite, editable at runtime |
+| Show selected evidence cards | **presentation data tool** (`presentation`, no `request`) | the tool store; see [Tools](../TOOLS.md#presentation-tools-the-model-picks-ids-the-engine-shows-the-cards) |
 | Logic must run in-process | **code tool** (a Ruby class `< RubyLLM::Tool`) | the deployment image |
 | Adopt a whole external MCP server | **`mcp` instance** | durable config; its tools appear tagged `mcp:<name>` |
 | Teach a procedure (no data fetching) | **skill** (`skill "name", description:, instructions:`) | loads on demand via `load_skill` |
@@ -78,6 +79,12 @@ RULES:
   verbatim and arguments are checked against it at call time.
 - Author the FINAL url: the HTTP client does not follow redirects, and the egress guard
   cleared that host only.
+- For a write that accepts catalog IDs, declare `requires_evidence` for those
+  parameters and ensure an allowed lookup declares `evidence`. Mark the write
+  `side_effect: true`; the engine serializes marked writes within a session.
+- For presentation, follow the [card contract](../TOOLS.md#presentation-tools-the-model-picks-ids-the-engine-shows-the-cards):
+  pass known IDs to the presentation tool. Look up again if their cards are absent
+  from the session ledger or current information is needed.
 - Do not add a second capability "while we're here".
 
 ## Step 3 — Make sure it enters the tool-loop
@@ -96,8 +103,11 @@ instead of fighting it.
 ## Step 4 — Prove it with ONE turn
 
 Run one `reply()` whose message forces the call ("how many BRL is 1 USD right now?").
-The reply must use what the tool returned — if the model answers from imagination, the
-tool did not run: re-check Step 3 before touching the prompt.
+Inspect the trace to confirm the call and result; the reply alone is not proof.
+For a gated write, also verify that an unknown ID is blocked before any backend
+request. For presentation, verify the selected `insika.ui` items. Use
+[snapshot eval assertions](../EVALS.md#graders--what-a-turns-calls-and-reply-are-checked-against)
+when the flow needs a repeatable precondition.
 
 ## Step 5 — Self-check
 

data/docs/prompts/DIAGNOSE-TURN.md

@@ -43,6 +43,9 @@ text), roughly **when**, and expected vs. actual. Reproduce once locally if chea
 | turn completed, customer got nothing | delivery is separate from the turn: check `channel_delivered` / `delivery_failed` | [Channels](../CHANNELS.md) |
 | freshly created agent returns empty turns | persona overflows the default `context_budget` (8000) | [Context](../CONTEXT.md) |
 | tool never called (or "missing") | not registered OR not allowed (`tools_allow`) | [Tools](../TOOLS.md) § troubleshooting |
+| `tool_blocked` with `gate: provenance` | ID absent from session evidence; look up before retrying | [Tools](../TOOLS.md#provenance-checking-ids-before-a-write) |
+| presentation shows no cards | inspect dropped IDs: `unknown`, `no_card`, `max`; a known ID may have no retained card | [API](../API.md#tool-and-presentation-sse-events) |
+| cache reuse dropped | compare identity/tool-schema fingerprints with provider cache token accounting | [Context](../CONTEXT.md#the-provider-prefix-cache) |
 | identical `tool_call` repeated, then abort | the `max_tool_repeat` loop guard | [Agents](../AGENTS.md) § limits |
 | model gave up after one empty result | `tool_persistence` off (it is ON by default) | same |
 | `turn_stuck` event | the agent declared it cannot proceed — escalation signal, not a bug | [Agents](../AGENTS.md) § stuck |

data/docs/prompts/GO-LIVE.md

@@ -40,7 +40,7 @@ convenience only:
 | Token | Gates | Rotating it |
 |---|---|---|
 | `ADMIN_TOKEN` | `/studio` login (the operator — just you) | safe, independent |
-| `OPENCLAW_GATEWAY_TOKEN` | Bearer for `/v1/responses` + `/v1/agents` (your API consumers) | both sides together, same step |
+| `INSIKA_GATEWAY_TOKEN` | Bearer for `/v1/responses` + `/v1/agents` (your API consumers) | both sides together, same step |
 
 Generate each: `ruby -rsecurerandom -e 'puts SecureRandom.hex(24)'`. Set them as
 platform env vars. **Never** write either into a file, a commit, or your own output.
@@ -77,7 +77,7 @@ Any Docker host, same contract:
 ```bash
 docker build -t insika .
 docker run -p 9292:9292 -v insika-data:/data \
-  -e DEEPSEEK_API_KEY=... -e ADMIN_TOKEN=... -e OPENCLAW_GATEWAY_TOKEN=... \
+  -e DEEPSEEK_API_KEY=... -e ADMIN_TOKEN=... -e INSIKA_GATEWAY_TOKEN=... \
   insika
 ```
 
@@ -87,12 +87,14 @@ In order, each with evidence:
 
 1. `curl https://<host>/up` → `{"status":"ok"}`.
 2. `bin/insika doctor` against the deployed volume (or via the platform's shell) —
-   relay its findings verbatim; fix errors before continuing.
+   relay its findings verbatim; fix errors before continuing. Check evidence sources
+   for gated writes/presentation, review the fencing warning, and leave
+   `evals.seeding` off after snapshot evals. See [Deploy](../DEPLOY.md#strict-config-and-insika-doctor).
 3. One authenticated turn:
 
 ```bash
 curl -N https://<host>/v1/responses \
-  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
+  -H "Authorization: Bearer $INSIKA_GATEWAY_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"model":"<agent-id>","user":"go-live-check","input":"hello"}'
 ```

data/lib/insika/agent_profile.rb

@@ -57,13 +57,15 @@ module Insika
     :prompt_caching,                  # Anthropic prompt caching (R3): nil/false = OFF
     #                                   (parity); true = ON. Same opt-in as `memory`. When ON
     #                                   AND the resolved provider is Anthropic, ChatBuilder sets
-    #                                   ONE cache breakpoint at the end of the system block
-    #                                   (caches tools+system by the tools->system->messages
-    #                                   prefix order; immune to history eviction). PRE-AUDIT:
-    #                                   the system prompt MUST be byte-stable between turns —
-    #                                   a context provider injecting volatile content into
-    #                                   :system turns every turn into a paid cache WRITE with
-    #                                   no read hit. Enable only for stable-system agents.
+    #                                   the cache breakpoint at the end of the IDENTITY layer
+    #                                   of the system (prompt, skills, tool index); memory,
+    #                                   knowledge and briefing render below it as a second
+    #                                   block, so a per-turn change there never re-writes the
+    #                                   cached prefix. Immune to history eviction too
+    #                                   (tools->system->messages prefix order). What still
+    #                                   costs a WRITE every turn: a provider declaring
+    #                                   `layer :identity` while emitting per-turn bytes —
+    #                                   the doctor's cache-layers check flags it.
     :tool_persistence,                # the engine's "Tool discipline" block in the system
     #                                   prompt (retry weak/empty tool results with a different
     #                                   approach before giving up). THE ONE OPT-OUT FIELD:
@@ -81,6 +83,16 @@ module Insika
     #                                   THE MODEL SEES: an older full result is only the first
     #                                   occurrence; a model that wants an older detail re-calls
     #                                   the tool. Cheap half of compaction for bloated histories.
+    :fencing,                         # third-party text is sanitized before the model reads
+    #                                   it: nil/false = OFF (parity — bytes reach the model
+    #                                   as-is); true = ON. Same opt-in as `memory`. When ON,
+    #                                   every tool result (after the evidence reshape), every
+    #                                   <memory> fact/note and every <knowledge> concept pass
+    #                                   Insika::Fence (NFKC, invisible/control characters out,
+    #                                   transcript- and tool-call-shaped tags removed, forged
+    #                                   turn markers defused, per-leaf cap), and the FenceNotice
+    #                                   sentence rides under the identity. Default OFF this
+    #                                   release: the goldens were baselined on unfenced bytes.
     :params,                          # LLM generation params: a Hash with
     #                                   temperature/max_tokens/thinking, applied to the chat at
     #                                   stage 5. {} = provider defaults (parity).
@@ -322,7 +334,7 @@ module Insika
                    policies: [], prompt_refs: [], limits: {}, approvals_required: nil,
                    capabilities: nil, subagents: nil, tools_deferred: nil, memory: nil,
                    prompt_caching: nil, tool_persistence: nil, tool_output_compression: nil,
-                    params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
+                   fencing: nil, params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
                     refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {},
                      budget: nil, reliability: nil, alerts: nil, routes: nil, stuck_signal: nil,
 outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil,
@@ -333,7 +345,9 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
         tools_deny: Array(tools_deny), tools_allow_groups: tools_allow_groups, skills: skills,
         skills_eager: skills_eager,
         context_providers: context_providers, workflows_allow: workflows_allow,
-        policies: Array(policies), prompt_refs: Array(prompt_refs),
+        policies: normalize_policies(policies, tools_allow: tools_allow, tools_deny: tools_deny,
+                                     tools_allow_groups: tools_allow_groups),
+        prompt_refs: Array(prompt_refs),
         limits: DEFAULT_LIMITS.merge(limits), approvals_required: approvals_required,
         capabilities: capabilities,
         # opt-in like capabilities: nil => NONE. Array-normalize a present value so
@@ -341,7 +355,7 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
         subagents: subagents.nil? ? nil : Array(subagents).map(&:to_s),
         tools_deferred: tools_deferred, memory: memory,
         prompt_caching: prompt_caching, tool_persistence: tool_persistence,
-        tool_output_compression: tool_output_compression,
+        tool_output_compression: tool_output_compression, fencing: fencing,
         # The free-form hashes arrive with symbol keys (internal build) OR string
         # keys (StoredProfileSource JSON round-trip). Normalize to string keys ONCE
         # here — the single front door every profile passes through — so no reader
@@ -400,6 +414,29 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
       )
     end
 
+    # Declaring a tool allow/deny list IS opting into it. The list is only ever
+    # applied by the builtin `tool_allowlist` policy, and the Policy::Engine runs
+    # ONLY the policies a profile names — so a profile with `tools_allow: [a, b]`
+    # and no policies sent EVERY registered tool to the model, silently. A
+    # declared allowlist that does nothing is the failure mode; same rule as the
+    # "mcp:<name>" group auto-added to `tools_allow_groups` by the DSL.
+    #
+    # Presence, not emptiness, is the trigger for the two nil-able lists:
+    # `tools_allow: []` means "no tools" and must enforce just as hard.
+    # `tools_deny` has no nil state (it defaults to []), so only a non-empty
+    # deny list counts as a declaration.
+    #
+    # Appended, never prepended: profile-declared policies keep their order. The
+    # engine intersects allows and unions denies, so position changes only the
+    # audit order, not the outcome.
+    def self.normalize_policies(policies, tools_allow:, tools_deny:, tools_allow_groups:)
+      names = Array(policies)
+      declared = !tools_allow.nil? || !tools_allow_groups.nil? || !Array(tools_deny).empty?
+      return names unless declared && names.none? { |n| n.to_s == "tool_allowlist" }
+
+      names + ["tool_allowlist"]
+    end
+
     # nil/absent -> nil; a single Hash -> [Hash]; else an Array of Hashes —
     # deep-stringified so JSON round-trips stay stable.
     def self.normalize_schedules(list)

data/lib/insika/channels/web/widget.js

@@ -158,6 +158,11 @@
             log.scrollTop = log.scrollHeight;
           } else if (event === "working" && !bubbleEl && !note) {
             note = say("note", "working…");
+          } else if (event === "ui" && data.items && data.items.length) {
+            // A presentation tool picked cards: a plain list of caption + link.
+            // The host page restyles or replaces this; the protocol is the frame.
+            if (note) { note.remove(); note = null; }
+            show(data);
           } else if (event === "error") {
             if (note) { note.remove(); note = null; }
             throw new Error(data.message || "something went wrong");
@@ -257,6 +262,34 @@
 
   // --- helpers --------------------------------------------------------
 
+  function show(ui) {
+    var list = el("ul", "insika-m ui");
+    if (ui.title) {
+      var head = el("li", "title");
+      head.textContent = ui.title;
+      list.appendChild(head);
+    }
+    ui.items.forEach(function (item) {
+      var li = el("li", "");
+      var label = item.caption || item.id || item.url;
+      // Only http(s) becomes a link: the url is backend data, and a
+      // `javascript:` or `data:` scheme must never be one click away.
+      if (/^https?:\/\//i.test(item.url || "")) {
+        var a = el("a", "");
+        a.href = item.url;
+        a.target = "_blank";
+        a.rel = "noopener";
+        a.textContent = label;
+        li.appendChild(a);
+      } else {
+        li.textContent = label;
+      }
+      list.appendChild(li);
+    });
+    log.appendChild(list);
+    log.scrollTop = log.scrollHeight;
+  }
+
   function say(kind, content) {
     var node = el("div", "insika-m " + kind);
     node.textContent = content;

data/lib/insika/channels/web.rb

@@ -155,8 +155,9 @@ module Insika
       # path — `POST /messages` with an unknown id is a 404, not a new conversation.
       def mint_session_id = "#{@id}:#{SecureRandom.hex(16)}"
 
-      # Turn Event -> SSE frame | nil. Four frames, which is the whole widget
-      # protocol: what to type, what to say while a tool runs, and how it ended.
+      # Turn Event -> SSE frame | nil. Five frames, which is the whole widget
+      # protocol: what to type, what to say while a tool runs, what to show
+      # (a presentation tool's cards), and how it ended.
       #
       # `:intermediate` and `:thinking` are deliberately absent. `:content` is the
       # ANSWER — the model's narration on the way there is internal, and a
@@ -165,6 +166,8 @@ module Insika
         case event.type
         when :content        then sse("delta", { delta: event.data[:delta].to_s })
         when :tool_call      then sse("working", { name: event.data[:name].to_s })
+        when :ui             then sse("ui", { component: event.data[:component].to_s, title: event.data[:title],
+                                              items: Array(event.data[:items]) })
         when :task_completed then sse("done", {})
         when :task_failed    then sse("error", { message: event.data[:message].to_s })
         when :task_cancelled then sse("error", { message: "task cancelled" })

data/lib/insika/chat_builder.rb

@@ -62,8 +62,7 @@ module Insika
 
     # Assembles the chat with the context (stage 2) and the Resolution's tools (stage 3).
     def configure_chat(chat, state)
-      system = state.context.system.to_s
-      apply_instructions(chat, system, state) unless system.empty?
+      apply_instructions(chat, state.context, state) unless state.context.system.to_s.empty?
 
       tools = Array(state.allowed_tools).dup
 
@@ -85,7 +84,8 @@ module Insika
         tools << Tools::ToolSearch.new(@tool_catalog, deferred_allowed, chat,
                                        tool_registry: @tool_registry,
                                        checkpoint_store: @checkpoint_store,
-                                       event_stream: @event_stream, state: state)
+                                       event_stream: @event_stream, state: state,
+                                       trace_recorder: @tool_trace_store)
       end
 
       # load_skill is a system default (outside the allowlist), otherwise
@@ -263,32 +263,60 @@ module Insika
                          ))
     end
 
-    # R3: opt-in Anthropic prompt caching. When the agent enables
-    # prompt_caching AND the resolved provider is Anthropic, wrap the system in
-    # the provider's native Content helper with cache: true — ONE breakpoint at
-    # the END of the system block. By Anthropic's prefix order
-    # (tools -> system -> messages), a breakpoint on the last system block caches
-    # tools + system together and is immune to history eviction (messages come
-    # after it). RubyLLM::Content::Raw is Anthropic-specific: build_system_content
-    # emits its blocks verbatim, so the cache_control rides along.
+    # Opt-in Anthropic prompt caching. When the agent enables prompt_caching
+    # AND the resolved provider is Anthropic, the system goes on the wire as TWO
+    # text blocks: the identity layer (prompt, skills, tool index) with the
+    # cache breakpoint at its end, then the volatile layer (memory, knowledge,
+    # briefing, request) plain. By Anthropic's prefix order
+    # (tools -> system -> messages) the breakpoint caches tools + identity
+    # together, immune to history eviction (messages come after it) AND to a
+    # memory fact or knowledge hit changing between turns (those bytes sit below
+    # the breakpoint, so they never enter the cached prefix). An empty volatile
+    # layer emits ONE block — byte-identical to the pre-split shape.
+    # RubyLLM::Content::Raw is Anthropic-specific: build_system_content emits
+    # its blocks verbatim, so the cache_control rides along.
     #
     # Any other case (caching off, or a non-Anthropic provider) uses the plain
     # string — OpenAI caches its prefix on its own; the Raw shape would confuse
     # non-Anthropic providers. The gem only supports MANUAL caching, and only for
     # Anthropic.
     #
-    # PRE-AUDIT (why this is opt-in): the system must be BYTE-STABLE between turns
-    # for a read hit. A context provider that injects volatile content into
-    # :system (timestamps, per-turn data) makes every turn a paid cache WRITE
-    # with no hit — worse than off. Enable only for stable-system agents.
-    def apply_instructions(chat, system, state)
+    # What still breaks a read hit: a context provider that declares
+    # `layer :identity` and emits per-turn bytes (a timestamp, request data).
+    # The doctor's cache-layers check flags exactly that; the Studio cache tab
+    # shows it as `broke: <category>`.
+    def apply_instructions(chat, context, state)
       if state.profile.prompt_caching && anthropic_provider?(chat)
-        chat.with_instructions(RubyLLM::Providers::Anthropic::Content.new(system, cache: true))
+        chat.with_instructions(RubyLLM::Providers::Anthropic::Content.new(parts: cache_blocks(context)))
       else
-        chat.with_instructions(system)
+        chat.with_instructions(context.system.to_s)
       end
     end
 
+    # [{type:, text:, cache_control:?}] — identity block with the breakpoint,
+    # volatile block plain. Empty texts are skipped (Anthropic rejects an empty
+    # text block). `system` is authoritative: a package without the split (a
+    # custom builder's Struct) or one whose `system` was rewritten alone (an
+    # after_prompt hook doing `pkg.with(system: …)`) reads as all-identity —
+    # one block over the whole text, never bytes the hook did not put there.
+    def cache_blocks(context)
+      identity, volatile = system_layers(context)
+      blocks = []
+      blocks << { type: "text", text: identity, cache_control: { type: "ephemeral" } } unless identity.empty?
+      blocks << { type: "text", text: volatile } unless volatile.empty?
+      blocks
+    end
+
+    def system_layers(context)
+      system = context.system.to_s
+      return [system, ""] unless context.respond_to?(:system_volatile)
+
+      identity = context.system_identity.to_s
+      volatile = context.system_volatile.to_s
+      joined = [identity, volatile].reject(&:empty?).join("\n\n")
+      joined == system ? [identity, volatile] : [system, ""]
+    end
+
     # The RESOLVED provider (chat.model.provider is the slug string, e.g.
     # "anthropic"), authoritative even when the agent left provider nil and
     # RubyLLM inferred it from the model id. Any surface without a model (fakes,
@@ -332,20 +360,29 @@ module Insika
     end
 
     # RubyLLM's additive callbacks become events. load_skill becomes
-    # :skill_activated. Adds the max_tool_calls counter: the loop is RubyLLM's;
-    # here we only count and abort.
+    # :skill_activated. Hangs the turn's TurnBudget on them: the loop is
+    # RubyLLM's; here we only count, warn and abort.
     def wire_callbacks(chat, state, emit)
-      # Per-TURN counter: safe as a closure local even under concurrent tool calls
-      # (MRI fibers do not preempt between the read and the write). The per-CALL
-      # correlation is NOT — it lives in fiber storage behind TurnState, because
-      # each call gets its own fiber once tool concurrency is on.
-      tool_calls = 0
-      max_tool_calls = state.profile.limits[:max_tool_calls] || 50
+      # The turn's ONE tool-call counter. Safe as a closure-held object even
+      # under concurrent tool calls (MRI fibers do not preempt between the read
+      # and the write). The per-CALL correlation is NOT — it lives in fiber
+      # storage behind TurnState, because each call gets its own fiber once tool
+      # concurrency is on.
+      #
+      # It counts, warns at 10/5/2 calls remaining, and raises the
+      # `stage: :tool_limit` abort — the guard-rail that used to be inline here.
+      # Announcing the budget needs #add_message at the batch boundary; a chat
+      # without it (smoke shim, minimal double) still gets the count and the
+      # abort, just no notice.
+      budget = Insika::TurnBudget.new(
+        chat: chat, max: state.profile.limits[:max_tool_calls] || 50, emit: emit
+      )
 
       # the loop detector. Needs #after_message + #add_message for the
       # batch-boundary intervention; a chat without them (smoke shim, minimal
       # double) stays bounded by max_tool_calls alone — never half-wired.
-      detector = if %i[after_message add_message].all? { |m| chat.respond_to?(m) }
+      appendable = %i[after_message add_message].all? { |m| chat.respond_to?(m) }
+      detector = if appendable
                    repeat = state.profile.limits[:max_tool_repeat] || Insika::AgentProfile::DEFAULT_LIMITS[:max_tool_repeat]
                    Insika::LoopDetector.new(chat: chat, limit: repeat, emit: emit) if repeat >= 2
                  end
@@ -355,11 +392,7 @@ module Insika
         state.current_tool_call = tool_call
         # max_tool_calls guard-rail: stays inline (not as a registered hook)
         # because Hooks is shared across turns and has no unregister.
-        tool_calls += 1
-        if tool_calls > max_tool_calls
-          raise Insika::TimeoutError.new("tool call limit exceeded (#{max_tool_calls})",
-                                           stage: :tool_limit)
-        end
+        budget.tool_call
 
         # AFTER the count, BEFORE the call runs — a post-warning
         # repeat raises here, so the stubborn loop pays for no extra call.
@@ -386,7 +419,7 @@ module Insika
           args = tool_call.arguments || {}
           emit.call(:knowledge_retrieved, { name: args["name"] || args[:name], agent: state.profile.id })
         else
-          emit.call(:tool_call, { name: tool_call.name, arguments: tool_call.arguments })
+          emit.call(:tool_call, { name: tool_call.name, arguments: tool_call.arguments, call_id: tool_call.id }.compact)
         end
       end
 
@@ -394,13 +427,33 @@ module Insika
         # the RAW result — the only place a Tool::Halt (halt_when) is
         # still recognizable, and a halted batch must receive no intervention.
         detector&.tool_result(result)
+        budget.tool_result(result)
         result = @hooks.run_after(:tool, result)
-        emit.call(:tool_result, { name: state.current_tool_name, result: result.to_s })
+        emit.call(:tool_result, { name: state.current_tool_name, call_id: state.current_tool_call&.id,
+                                  result: result.to_s }.compact.merge(tool_outcome(result)))
       end
 
-      # the intervention appends at the batch boundary (the Nth tool
-      # result closing) — never between two tool results of one batch.
-      chat.after_message { |message| detector.message_ended(message) } if detector
+      # both appends land at the batch boundary (the Nth tool result closing) —
+      # never between two tool results of one batch.
+      return unless appendable
+
+      chat.after_message do |message|
+        detector&.message_ended(message)
+        budget.message_ended(message)
+      end
+    end
+
+    # How the call ENDED, for the :tool_result event (the edge publishes it and the
+    # evals grade it): the envelope's `{error:}` -> "error"; a gate that held the
+    # call (ToolEnvelope::Blocked) -> "blocked" + which gate; anything else ran ->
+    # "ok" — including a tool whose OWN answer happens to say "blocked". Read off
+    # the RAW result, before it is stringified for the event.
+    def tool_outcome(result)
+      return { status: "blocked", gate: result["gate"]&.to_s }.compact if result.is_a?(Insika::ToolEnvelope::Blocked)
+      return { status: "ok" } unless result.is_a?(Hash)
+      return { status: "error" } if result.key?(:error) || result.key?("error")
+
+      { status: "ok" }
     end
   end
 end

data/lib/insika/commands/agent_payload.rb

@@ -12,7 +12,7 @@ module Insika
       FIELDS = %i[id model provider base_prompt prompt_files tools_allow tools_deny
                   tools_allow_groups skills skills_eager context_providers workflows_allow policies
                   prompt_refs limits approvals_required capabilities subagents tools_deferred
-                  memory prompt_caching tool_persistence tool_output_compression budget reliability alerts
+                  memory prompt_caching tool_persistence tool_output_compression fencing budget reliability alerts
                   routes stuck_signal outputs stt_prompt briefing_fields grounding funnel followup
                   params model_policy guardrails refinement capabilities_declared
                   edge_stream metadata distill harvest knowledge schedules].freeze

data/lib/insika/commands/run_distillation.rb

@@ -148,8 +148,8 @@ module Insika
         !applied.nil? && applied.value == value && applied.origin.to_s.start_with?("distilled:")
       end
 
-      # The prompt gets the transcript slice (masked through the
-      # output filter first — the   redaction rule), the
+      # The prompt gets the transcript slice (user/assistant only, masked
+      # through the output filter — the redaction rule), the
       # customer's CURRENT facts (so the model can avoid re-proposing applied
       # facts), and the answer rules (the pack prompt or DEFAULT_PROMPT).
       def build_prompt(config, session, baseline)
@@ -169,12 +169,9 @@ module Insika
         PROMPT
       end
 
-      def render_transcript(messages)
-        redacted, = Insika::Safety::Detectors.redact(
-          messages.each_with_index.map { |m, i| "[#{i}] #{m['role']}: #{m['content']}" }.join("\n")
-        )
-        redacted
-      end
+      # Only what people said — a `role: tool` message (a product description,
+      # a search result) is never a candidate customer fact.
+      def render_transcript(messages) = Insika::SpokenTranscript.render(messages)
 
       def utility_model
         return nil unless @settings_store

data/lib/insika/commands/seed_session.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: loads a SNAPSHOT into a conversation before its first
+    # turn — the precondition an eval case starts from ("the customer already saw
+    # three products", "a stored preference"), without replaying the turns that
+    # would have produced it. Creates the session when it does not exist yet, then
+    # writes the four kinds of state a turn reads:
+    #
+    #   history:  [{ role:, content: }] -> the transcript, stamped `origin: engine`
+    #             (nobody typed these; a report must not read them as the customer)
+    #   evidence: { ids: [], cards: [] }   -> the session evidence ledger (cards
+    #             carry an `id`; a presentation tool shows them)
+    #   memory:   { facts: {}, notes: [] } -> the memory cell THIS turn will read
+    #   briefing: { fields: {} }           -> the session briefing
+    #
+    # Refuses a session that already has messages (ConflictError -> 409): seeding a
+    # used conversation is a test bug, not a merge — the case would assert against a
+    # state nobody wrote down. Synchronous; does not create a Task. -> Session.
+    class SeedSession
+      def initialize(session_store:, memory_store:, event_stream:)
+        @session_store = session_store
+        @memory_store = memory_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        id = AgentPayload.presence(p[:id])
+        raise Insika::ValidationError, "id is required" if id.nil?
+
+        state = Coercion.deep_stringify(p[:state] || {})
+        raise Insika::ValidationError, "state must be a Hash" unless state.is_a?(Hash)
+
+        tenant = command.meta[:tenant] # the same source the turn reads — never the payload
+        customer = AgentPayload.presence(p[:customer])
+
+        session = @session_store.find(id) || @session_store.create(id: id, vars: {})
+        unless session.messages.empty?
+          raise Insika::ConflictError,
+                "session #{id} already has #{session.messages.size} message(s) — seed a fresh conversation"
+        end
+
+        seed_history(id, state["history"])
+        seed_evidence(id, state["evidence"])
+        seed_memory(memory_scope(tenant, customer, id), state["memory"])
+        seed_briefing(id, state["briefing"])
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :session_seeded,
+                             data: { session_id: id, tenant: tenant, keys: state.keys }.compact,
+                             meta: { session_id: id, at: Time.now.utc.iso8601 }
+                           ))
+        @session_store.find(id)
+      end
+
+      private
+
+      def seed_history(id, history)
+        return if history.nil?
+        raise Insika::ValidationError, "state.history must be an array" unless history.is_a?(Array)
+
+        messages = history.map do |m|
+          raise Insika::ValidationError, "state.history entries must be { role:, content: }" unless m.is_a?(Hash)
+
+          role = m["role"].to_s
+          unless %w[user assistant].include?(role)
+            raise Insika::ValidationError, "state.history role must be user or assistant (got #{role.inspect})"
+          end
+
+          { "role" => role, "content" => m["content"].to_s, "origin" => Insika::MessageOrigin::ENGINE }
+        end
+        @session_store.append_messages(id, messages) unless messages.empty?
+      end
+
+      def seed_evidence(id, evidence)
+        return if evidence.nil?
+        raise Insika::ValidationError, "state.evidence must be { ids: [], cards: [] }" unless evidence.is_a?(Hash)
+
+        ids = Array(evidence["ids"]).map(&:to_s).reject(&:empty?)
+        cards = Insika::Evidence.valid_attachments(evidence["cards"]).select { |c| c["id"] }
+        # a card's id counts as seen: the card came from a search the case declares
+        ids = (ids + cards.map { |c| c["id"] }).uniq
+        @session_store.append_evidence(id, ids: ids, ungrounded: 0, cards: cards) unless ids.empty?
+      end
+
+      def seed_memory(scope, memory)
+        return if memory.nil?
+        raise Insika::ValidationError, "state.memory must be { facts: {}, notes: [] }" unless memory.is_a?(Hash)
+
+        facts = memory["facts"] || {}
+        raise Insika::ValidationError, "state.memory.facts must be a Hash" unless facts.is_a?(Hash)
+
+        facts.each { |key, value| @memory_store.put_fact(tenant: scope, key: key, value: value, origin: "operator") }
+        Array(memory["notes"]).each { |text| @memory_store.add_note(tenant: scope, text: text.to_s) }
+      end
+
+      def seed_briefing(id, briefing)
+        return if briefing.nil?
+        raise Insika::ValidationError, "state.briefing must be { fields: {} }" unless briefing.is_a?(Hash)
+
+        fields = briefing["fields"] || {}
+        raise Insika::ValidationError, "state.briefing.fields must be a Hash" unless fields.is_a?(Hash)
+
+        fields.each { |field, value| @session_store.update_briefing(id, field: field, value: value) }
+      end
+
+      # The SAME cell the turn will read — one rule, MemoryStore.scope_for. Seeding
+      # any other cell would pass the case against a memory the model never sees.
+      def memory_scope(tenant, customer, session_id)
+        MemoryStore.scope_for(tenant: tenant, customer: customer, session_id: session_id)
+      end
+    end
+  end
+end