insika 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 345e57c18a277e8ecd49b2481300c1474c60b2e0c3c384a086740e0de5ec3a2e
-  data.tar.gz: 800794431e279fec34f135e4e203a0488b04066b667bc691806ea5f575d81530
+  metadata.gz: ec89eb1dae94e5a57733d0dd88a19d92ff98eb7e2ae0b907792e2a4ce8d508aa
+  data.tar.gz: cb882c8015e00c0c905e5945a05a5a465c938dedda762914c3737a64a9f0d4fb
 SHA512:
-  metadata.gz: 199cc16b9ea651ec2da1d2e6f7ddea5020194882da00cf96981e8d5d44086233862873d14640d11cd1d445f9d202992ed46691210f9fb1699b1a3d56a99b3145
-  data.tar.gz: 44d24bc53036da3803ee6eba6203d1addc8ccf0bd27c1aa15d1e9acfe763bca807ede55c2b7136ee2c245e5cd725541c719baa018c99e09638e964803bf688a9
+  metadata.gz: e2acb07f2ae896ee762cd3f1113dca3d462f80ea0bb32caea69f5db3fd6fbd31821cf9a5140b32c64c26b702b29b78aaf9fec0ca8f59653178dcb37afe9eca38
+  data.tar.gz: f8c98a2b76c802a75e18a77e0762ef42c650aa956afb3f131e1e9ccacfb2a56de87540b7389c740021008b45a174fa371d7a6dbb0a5a7cf83f248ce41b696770

data/CHANGELOG.md

@@ -8,6 +8,81 @@ it is released. Entries land with the pull request that makes the change.
 
 ## [Unreleased]
 
+## [0.9.0] - 2026-09-07
+
+The commerce-agent wave: the engine now enforces what the prompt used to ask for —
+a write names only IDs a lookup returned, the model picks which cards to show and
+the engine shows them, third-party text can be fenced before the model reads it,
+and an eval case can start from a seeded snapshot. Additive on the wire: `/v1`
+gains frames and keys, none change meaning.
+
+### Added
+
+- **Write provenance** — `requires_evidence` on HTTP data tools checks declared
+  ID parameters against the session evidence ledger before approval or execution.
+  Unknown IDs and an unavailable ledger return `blocked` with gate `provenance`.
+  Studio editing, Doctor diagnostics, session traces, `tool_blocked`, the
+  `insika.tool.blocked` counter and `insika tools:report` expose the gate.
+  See [Tools](docs/TOOLS.md#provenance-checking-ids-before-a-write).
+- **Snapshot evals** — cases can seed evidence IDs, memory, user/assistant history
+  and briefing before the first turn. The authenticated seed endpoint is disabled
+  by default (`evals.seeding`); Doctor warns when enabled. New assertions cover
+  forbidden/alternative/first calls, call limits, reply text and blocked gates.
+  Responses SSE now carries tool arguments, completion status and the provider's
+  `call_id` on both item frames, so a consumer pairs `added` with `done`.
+  See [Evals](docs/EVALS.md#state--a-case-starts-from-a-snapshot).
+- **Presentation tools** — data tools with `presentation` instead of `request`
+  select evidence cards by known ID — this turn's, or the last 64 the session
+  ledger kept (snapshots seed them as `evidence.cards`). They report shown/dropped IDs,
+  emit `insika.ui` (web channel: `ui`) and select the outbox attachments. Evidence
+  cards carry IDs; empty selections suppress automatic card delivery. Includes
+  `ui_components` / `no_ui` eval assertions and Doctor diagnostics.
+  See [Tools](docs/TOOLS.md#presentation-tools-the-model-picks-ids-the-engine-shows-the-cards).
+- **Fencing** — opt-in per agent through the DSL, payload or Studio. Sanitizes
+  ordinary tool result strings, memory text and injected knowledge summaries, and adds a fixed
+  identity-layer notice. The tool-string cap `fencing.max_chars` defaults to 12,000; the agent flag
+  defaults to off — and stays off in this release: flipping the default waits for the
+  golden-case comparison with fencing on ([Releasing](docs/RELEASING.md), gate 4).
+  Doctor warns for unfenced agents exposed by relay/widget env configuration.
+  See [Agents](docs/AGENTS.md#fencing--third-party-text-is-data-never-instructions).
+
+### Changed
+
+- **Cache boundary** — explicit Anthropic cache control ends at the identity layer;
+  volatile system text follows in a separate block. Prefix fingerprints cover
+  identity and tool schemas; memory/knowledge/request changes retain separate
+  diagnostic digests without reporting identity-prefix invalidation.
+  See [Context](docs/CONTEXT.md#the-provider-prefix-cache).
+- **Serial writes in parallel batches** — tools marked `side_effect` acquire a
+  per-session serial gate before the shared concurrency slot. Independent reads
+  can overlap writes; queued writes do not consume that shared slot. MCP tools
+  annotated `readOnlyHint` are reads.
+- Memory and knowledge extraction read only nonblank user/assistant text, preserving
+  original transcript indexes. Direct tool messages are excluded; assistant
+  paraphrases can still reach extraction. This applies regardless of `fencing`.
+- A tool's own `{"status":"blocked"}` answer is a call that ran: only the engine's
+  gate refusal reports `blocked` on `:tool_result`, the trace and `tools:report`.
+- A Studio save that changes a tool's HTTP method re-derives `side_effect`.
+
+### Fixed
+
+- Data tools declaring `evidence` no longer fail when the envelope parses an
+  already-parsed `Evidence::Spec`.
+- Studio tool saves preserve `evidence` and `presentation` declarations.
+- `scripts/serve_real.rb` passes channel and settings stores to the edge, enabling
+  configured relay/widget routes and the eval seeding setting in the demo server.
+- Fencing: the notice ships with the flag regardless of the `context_providers`
+  allowlist; briefing values and the compaction summary are sanitized too; evidence
+  item ids stay byte-exact for the model (only the line is sanitized).
+- Provenance: a schema-optional parameter the model omits is not checked; a blocked
+  call on a one-shot turn no longer fails emitting `tool_blocked`.
+- `POST /v1/conversations/:id/seed` decodes a percent-encoded conversation id.
+- Widget `ui` cards link only `http(s)` urls.
+- The evidence ledger reads the session row once per turn, not once per gated call.
+- Studio reads its templates as UTF-8 regardless of the process locale: a host with
+  no `LANG` answered 500 on the login page (found by the release install proof).
+
+
 ## [0.8.0] - 2026-08-31
 
 The post-consolidation hardening wave: the last two OpenClaw-era names are gone

data/README.md

@@ -18,7 +18,9 @@ deployment.
 - **Drop-in `/v1/responses`** — SSE streaming and usage, the shape existing clients already speak.
 - **Durable & resumable** — every turn checkpoints; a crash resumes without repeating side-effects.
 - **Agents as data** — agents, prompts, skills and tools are editable at runtime (UI or API), no redeploy.
-- **Tools & skills** — code tools, data-defined tools, MCP import; skills load on demand.
+- **Tools & skills** — code, HTTP data and live MCP tools; skills load on demand.
+- **Evidence-backed actions** — ID checks before writes, serial side effects per session, and selected evidence cards ([Tools](docs/TOOLS.md)).
+- **Snapshot evals** — seed a case's starting state and check calls, refusals, replies and cards ([Evals](docs/EVALS.md)).
 - **Safe by default** — content-safety guardrails, an egress guard, confined execution, approvals, edge limits.
 - **Observable** — an event stream, per-session tool-call traces, optional OpenTelemetry.
 - **~0.4 ms of engine per turn** — p50 overhead on a neutral, key-free benchmark you can rerun yourself ([methodology](docs/BENCHMARK.md)).
@@ -106,7 +108,7 @@ navigates by.
 
 - [Agents](docs/AGENTS.md) — the AgentProfile and every key on it; create and edit at runtime.
 - [Limits and policy](docs/POLICY.md) — the five layers: allowed tools, approvals, guardrails, edge limits, reasoning.
-- [Tools](docs/TOOLS.md) — code vs data vs MCP tools, manifests, egress troubleshooting.
+- [Tools](docs/TOOLS.md) — code, HTTP, MCP and presentation tools; evidence gates and serial writes.
 - [Skills](docs/SKILLS.md) — the SKILL.md format and progressive loading.
 - [Context](docs/CONTEXT.md) — what fills a turn's prompt; budget, eviction, memory.
 - [Workflows](docs/WORKFLOWS.md) — deterministic orchestration of several agents: the five patterns, and when to let the model choose instead.
@@ -140,7 +142,7 @@ navigates by.
 
 **Improve**
 
-- [Evals](docs/EVALS.md) — the cases that grade an agent: rubrics, the judge panel, and the pre-merge gate.
+- [Evals](docs/EVALS.md) — snapshot cases, tool/UI assertions, rubrics, the judge panel and the pre-merge gate.
 - [Refinement](docs/REFINEMENT.md) — read an agent's own traffic back as a ranked report of what broke.
 - [Outcomes and follow-ups](docs/OUTCOMES.md) — what the traffic was worth in business terms, and the tool that comes back on a promise.
 - [Knowledge](docs/KNOWLEDGE.md) — extract durable concepts from finished conversations into a per-agent knowledge base; provenance-stamped, PII-redacted, best-effort with a re-scan recovery path.

data/bin/insika

@@ -390,7 +390,7 @@ def evals_simulate(argv)
   # paired comparison, which it silently invalidates.
   require "securerandom"
   conv = opts[:conv] || "sim-#{golden.id}-#{SecureRandom.hex(4)}"
-  run = simulator.run(persona: golden.persona, agent: target_agent, conv: conv)
+  run = simulator.run(persona: golden.persona, agent: target_agent, conv: conv, state: golden.state)
 
   verdict = judge && judge.score_conversation(
     rubric: golden.rubric, transcript: run.transcript, policy: golden.policy,

data/docs/AGENTS.md

@@ -144,9 +144,44 @@ the thing worth declaring:
 tool_persistence false   # remove the block for this agent
 ```
 
-The block is a byte-stable constant, so `prompt_caching` stays effective: the
-deploy that introduces it costs one cache write per agent, and every turn after
-that hits as before.
+The block is constant, so it does not invalidate the identity prefix between turns.
+
+### `prompt_caching` — explicit cache control
+
+Set `"prompt_caching": true` in the agent payload, or enable it in the Studio
+agent configuration. There is no dedicated DSL method for this flag.
+
+For Anthropic, this puts the cache breakpoint after the identity layer and leaves
+volatile system text below it. Other providers receive a plain system string and
+may cache automatically. See [Context](CONTEXT.md#the-provider-prefix-cache) for
+layering, fallback behavior and token accounting.
+
+### `fencing` — third-party text is data, never instructions
+
+```ruby
+fencing true
+```
+
+Off by default. When enabled, the engine sanitizes ordinary tool result string
+leaves after evidence processing, memory facts/notes, briefing values and the next
+step, the compaction summary, and the knowledge names and descriptions injected in
+the context block. It normalizes Unicode (NFKC), removes invisible format characters,
+replaces control characters except tabs/newlines/carriage returns, strips known
+engine/transcript tag shapes and defuses forged role markers. Tool result strings
+are also capped at `fencing.max_chars` (platform default 12,000); memory and knowledge
+context sanitization does not apply that cap. Tool error and halt results bypass
+this sanitizer; tool Hash keys, evidence item `id`s and attachment captions are
+unchanged (an id is a key the ledger holds byte-exact).
+`load_knowledge` returns the full body without fencing.
+
+A fixed notice beneath the identity tells the model to treat contextual material
+as data. It ships with the flag — the `context_providers` allowlist does not govern
+it. It is stable across turns; it does not guarantee prompt-injection resistance.
+
+Memory/knowledge extraction reads only nonblank user/assistant text regardless
+of the flag. Direct tool messages are excluded, but text repeated by the
+assistant can still reach extraction. `insika doctor` warns for unfenced agents
+exposed by the configured relay/widget environment settings.
 
 ### Why some limits are missing from that list
 
@@ -173,17 +208,16 @@ So the two groups read differently on purpose:
 ### `tool_concurrency` — parallel tool calls
 
 When the model asks for several tools in one step, they run **one at a time by
-default**. Raise `tool_concurrency` and they run together, capped at that number
-in flight:
+default**. Raise `tool_concurrency` to overlap independent reads, capped at that
+number in flight. Tools marked `side_effect` still execute one at a time per session:
 
 ```ruby
 limit :tool_concurrency, 4   # nil / 0 / 1 = serial (the default); N = at most N at once
 ```
 
 One number is both the switch and the cap. It pays off only when a turn issues
-several **slow, independent** calls (data tools waiting on HTTP) — the wall-clock
-becomes the slowest call instead of the sum. It buys nothing for fast in-process
-tools, and it is the *model* that decides the fan-out, which is why the cap is not
+several **slow, independent reads** (data tools waiting on HTTP). It buys nothing
+for fast in-process tools, and it is the *model* that decides the fan-out, which is why the cap is not
 optional: an uncapped batch of 15 data tools is 15 simultaneous requests to the
 same backend.
 
@@ -405,9 +439,9 @@ Three capabilities invert the default — `nil`/absent means **OFF**, not "all":
 `subagents`, `memory`, and `guardrails` (each defaults to off or a conservative
 setting, never "everything on"). `tool_output_compression` is a fourth: opt-in
 mechanical dedupe of repeated tool results in the history (see
-[Context](CONTEXT.md#compaction-is-not-wired--except-the-mechanical-dedupe)),
-off by default because it changes what the model sees. And one flag inverts the
-other way: `tool_persistence` is **ON unless you set it to `false`** (see
+[Context](CONTEXT.md#budget-and-eviction--the-actual-compaction)),
+off by default because it changes what the model sees; `fencing` is a fifth (see
+[`fencing`](#fencing--third-party-text-is-data-never-instructions)), off by default. One flag inverts the other way: `tool_persistence` is **ON unless you set it to `false`** (see
 [`tool_persistence`](#tool_persistence--dont-give-up-on-the-first-empty-result)).
 
 ### Declaring what this deployment has
@@ -692,6 +726,13 @@ optionally shared outside the Studio via an expiring signed link
 saving agent — never a parameter the model types. Artifact content is LLM
 output and is served as untrusted. See [Artifacts](ARTIFACTS.md).
 
+## Review before enabling writes
+
+Does each ID come from the server? Declare `evidence` on the lookup tool and
+`requires_evidence` on the write tool so the engine enforces session provenance.
+Mark writes as `side_effect` so parallel batches serialize them and recovery skips
+completed calls. See [Tools](TOOLS.md#provenance-checking-ids-before-a-write).
+
 ## See also
 
 - [Tools](TOOLS.md) — define, register, and troubleshoot tools.

data/docs/API.md

@@ -21,6 +21,7 @@ two cannot drift (a spec pins the gate's version to the date below).
 | `POST /v1/agents` | provisioning by definition/pack (idempotent, authoritative) |
 | `GET/DELETE /v1/agents` | list / remove agents |
 | `POST /v1/sessions` | create a session explicitly |
+| `POST /v1/conversations/:id/seed` | load an eval snapshot before the first turn; see [Seeding](#seeding-an-eval-conversation) |
 | `POST /v1/outcomes` | record a business outcome (`conversion`, `escalation`, any label) |
 | `GET /v1/outcomes` | last outcome per agent + the per-day series |
 | `POST /v1/commands/...` | operator commands (`forget_customer`, `delete_tenant_data`, the follow-up mutations) |
@@ -30,6 +31,78 @@ two cannot drift (a spec pins the gate's version to the date below).
 The turn endpoints speak the OpenAI `response.completed` wire format; the
 `Insika-Version` header declares the compatibility vintage of a request.
 
+## Tool and presentation SSE events
+
+`POST /v1/responses` emits a tool name on `response.output_item.added`, with
+`arguments` as a JSON string when available. `response.output_item.done` reports
+how it ended. These `ok` / `error` / `blocked` statuses and optional `gate` are
+Insika extensions, not OpenAI function-call lifecycle statuses.
+
+```text
+event: response.output_item.added
+data: {"type":"response.output_item.added","item":{"type":"function_call","name":"add_to_cart","call_id":"toolu_01","arguments":"{\"product_id\":\"SKU-1\"}"}}
+
+event: response.output_item.done
+data: {"type":"response.output_item.done","item":{"type":"function_call","name":"add_to_cart","call_id":"toolu_01","status":"blocked","gate":"provenance"}}
+```
+
+`added` and `done` are two frames of **one** call, paired by `call_id` (the provider's
+tool-call id, present whenever the provider gave one). A consumer that counts tool
+calls counts `added` frames; `done` only says how each ended.
+
+The completion frame does not contain the tool result body. Use stored session
+traces for a per-call audit of what a tool returned.
+
+A presentation call also emits a namespaced event:
+
+```text
+event: insika.ui
+data: {"type":"insika.ui","component":"product_cards","title":"Selected products","items":[{"type":"card","id":"SKU-1","url":"https://shop.example/products/1","caption":"Dark chocolate"}],"count":1,"dropped":[{"id":"SKU-2","reason":"no_card"}]}
+```
+
+`count` is the number shown; `dropped` reasons are `unknown`, `no_card` or `max`.
+An empty selection still emits the event with `count: 0`. Clients that render
+cards consume this event; text-only clients can ignore it. See
+[Presentation tools](TOOLS.md#presentation-tools-the-model-picks-ids-the-engine-shows-the-cards).
+
+## Seeding an eval conversation
+
+Enable `evals.seeding` in platform settings on the eval deployment. For example,
+an operator can `POST /v1/commands/update_settings` with
+`{"patch":{"evals":{"seeding":true}}}`. Turn it off after the run.
+
+`POST /v1/conversations/:id/seed` uses the same Bearer and tenant ID namespacing
+as a turn. Its body is the snapshot itself, plus optional `customer`; do not wrap
+it in `state`:
+
+```json
+{
+  "customer": "eval-customer-1",
+  "evidence": {
+    "ids": ["SKU-1"],
+    "cards": [{ "type": "card", "id": "SKU-1", "url": "https://shop.example/1", "caption": "Dark chocolate" }]
+  },
+  "history": [
+    { "role": "assistant", "content": "The dark chocolate is SKU-1." }
+  ],
+  "memory": { "facts": { "preference": "dark chocolate" }, "notes": [] },
+  "briefing": { "fields": { "delivery_day": "Friday" } }
+}
+```
+
+It creates a missing session and returns `200` with `{ "session": … }`; seeding
+does not run a model or create a task. Disabled seeding returns `403`, a session
+with messages returns `409`, and invalid supported field shapes return `422`.
+History accepts only `user` / `assistant` roles and is stamped `origin: engine`.
+
+Memory uses `[tenant:]customer` when `customer` is supplied; subsequent turns
+must carry the same customer. Without one, memory is written to the tenant cell,
+or `chat:<session-id>` when there is no tenant. Use an isolated eval deployment:
+a fresh conversation ID alone does not isolate tenant memory. Evidence IDs seed
+only the runtime ledger, never model-visible text; `evidence.cards` seeds the cards
+a presentation tool can show.
+See [Snapshot evals](EVALS.md#state--a-case-starts-from-a-snapshot).
+
 ## The compatibility rule
 
 **Request and response shapes are stable; changes are additive-only.** A new

data/docs/ARCHITECTURE.md

@@ -177,64 +177,65 @@ The order is not arbitrary:
 
 ## The tool-loop
 
-Stage 6 is the single agent interaction. RubyLLM owns the reason→act→observe loop;
-the engine wraps each tool the model may call in a **ToolEnvelope** that enforces
-the per-tool timeout, records side-effects for checkpointing, skips
-already-completed side-effects on resume, and fires the approval gate.
+Stage 6 is the agent interaction. RubyLLM owns the reason→act→observe loop;
+`ToolEnvelope` adds provenance, approval, concurrency, timeout, evidence processing,
+fencing, traces and side-effect checkpoints around registered tools.
 
-When a step contains several tool calls they are executed **one at a time**, unless
-the agent raised `limits[:tool_concurrency]` — then the batch runs on the turn's
-reactor with at most that many in flight, one fiber per call, and the envelope's
-shared semaphore is the cap. A turn with an approval-required tool always runs
-serially. See [Tools](TOOLS.md#parallel-tool-calls) for what that changes.
+Calls run serially unless `limits[:tool_concurrency]` permits parallel execution.
+Marked side effects acquire a serial gate before the shared concurrency slot,
+so writes in one session cannot overlap and queued writes leave slots for reads.
+Turns exposing approval-required tools run serially. See
+[Tools](TOOLS.md#parallel-tool-calls) for limits and timeout behavior.
 
 ```mermaid
 flowchart TD
-  ask[chat.ask -> model] --> dec{tool call?}
+  ask[chat.ask → model] --> dec{tool call?}
   dec -->|no| done[final content]
-  dec -->|yes| env[ToolEnvelope]
-  env --> appr{approval<br/>required?}
-  appr -->|yes| suspend[[suspend turn<br/>await operator]]
-  suspend --> appr
-  appr -->|no / approved| kind{tool kind}
-  kind -->|code| ruby[Ruby class<br/>in-process / sandbox]
-  kind -->|data / MCP| egress[EgressGuard] --> http[(external HTTP)]
-  ruby --> obs[result -> back to model]
-  http --> obs
-  obs --> ask
+  dec -->|yes| env[ToolEnvelope: skip completed side effects on resume]
+  env --> prov{declared evidence IDs known?}
+  prov -->|no| blocked[blocked: provenance]
+  blocked --> ask
+  prov -->|yes / undeclared| appr[approval gate]
+  appr --> gates[side-effect serial gate → shared concurrency slot → timeout]
+  gates --> kind{tool kind}
+  kind -->|code| ruby[Ruby / sandbox]
+  kind -->|HTTP data| http[EgressGuard → HTTP]
+  kind -->|MCP| mcp[live MCP client]
+  kind -->|presentation| cards[select turn or session evidence cards → UI event]
+  ruby --> result[evidence reshape → fencing → checkpoint and trace]
+  http --> result
+  mcp --> result
+  cards --> result
+  result --> ask
 ```
 
-A **data tool** is config, not code (see [Tools](TOOLS.md)): its result comes back
-to the model exactly like a code tool's, but it went out over HTTP through the
-egress guard. A tool exception is caught and returned *to the model* as an error
-result — it does not crash the turn. Side-effecting tools (POST and friends) are
-recorded in the checkpoint so a resume does not re-run them.
+HTTP data tools and presentation tools are both stored definitions. Presentation
+runs in-process; MCP remains a live server call (HTTP/SSE or stdio). HTTP egress
+is checked before a request. Tool errors reach the model as error results so it
+can recover; a provenance refusal reports `blocked` without contacting the backend
+or asking an operator. Completed side effects are recorded for resume.
 
 ## Ingesting tools: manifest and MCP
 
-Tools become data in the store through two runtime paths, both hot (no restart):
+Data definitions and MCP instances have separate stores. Both are hot config:
 
 ```mermaid
 flowchart TD
-  subgraph manifest [Manifest path]
-    m["POST /v1/tools/manifest"] --> sub["substitute<br/>{{env.*}} / {{secret.*}}"]
-    sub --> val1[validate each tool]
-  end
-  subgraph mcp [MCP path]
-    srv[(MCP server<br/>HTTP transport)] --> ing[MCP ingestor]
-    ing --> conv[each tool → HTTP data tool<br/>JSON-RPC tools/call]
-    conv --> val2[validate]
-  end
-  val1 --> store[(ToolStore)]
-  val2 --> store
-  store --> cat[reload catalog + registry]
-  cat --> loop[available in the tool-loop]
+  manifest[POST /v1/tools/manifest] --> substitute[resolve env / secret placeholders]
+  substitute --> validate[validate HTTP or presentation definition]
+  validate --> store[(ToolStore)]
+  store --> data[DataToolRegistry]
+  config[MCP instance configuration] --> mcpstore[(McpStore)]
+  mcpstore --> live[McpToolRegistry → live server tools]
+  data --> catalog[effective registry and catalog]
+  live --> catalog
+  catalog --> policy[agent allowlist → tool-loop]
 ```
 
-The manifest path is the **only** one that resolves `{{env.*}}` (at ingestion);
-every other write path requires a literal URL. Partial failure on the manifest
-path is isolated — one malformed tool is reported in `errors[]` while the rest
-import. See [Tools](TOOLS.md#registering-a-tool).
+Only manifest ingestion resolves `{{env.*}}` and `{{secret.*}}`; other data-tool
+write paths require literal values. One malformed manifest tool is reported in
+`errors[]` while valid entries import. MCP tools are never converted to stored
+HTTP data tools. See [Tools](TOOLS.md#registering-a-tool).
 
 ## Durability: checkpoints and resume
 
@@ -316,7 +317,7 @@ validator as the after-task hook, so both roots enforce content safety identical
 | Recovery | `lib/insika/recovery.rb` |
 | Inbound queue (one turn at a time per session, and what happens to a message that arrives while one is running) | `lib/insika/session_actor.rb`, `lib/insika/queue_policy.rb`, `lib/insika/steer_injector.rb` |
 | Channels (a way in and out for people; the reply that travels after the turn ends) | `lib/insika/channel_registry.rb`, `lib/insika/channels/*`, `lib/insika/channel_delivery.rb`, `lib/insika/outbox_store.rb`, `lib/insika/inbound_log.rb` |
-| Tools (data/manifest/MCP) | `lib/insika/tool_definition.rb`, `tool_manifest.rb`, `mcp_tool_ingestor.rb` |
+| Tools (data/manifest/MCP) | `lib/insika/tool_definition.rb`, `lib/insika/tool_manifest.rb`, `lib/insika/mcp_tool_registry.rb`, `lib/insika/tools/present.rb` |
 | Plugin loading (boot) | `lib/insika/plugin.rb`, `lib/insika/plugin/loader.rb` |
 | Refinement (traffic → report) | `lib/insika/refinement/*`, `lib/insika/refinement_store.rb` |
 | Post-turn learning (facts, skills, knowledge — extracted from finished conversations) | `lib/insika/distill.rb`, `lib/insika/harvest.rb`, `lib/insika/knowledge.rb`, `lib/insika/knowledge_store.rb`; the per-turn hook lives in `Executor#persist_turn`, next to `finalize_delegation` |

data/docs/CHANNELS.md

@@ -149,16 +149,24 @@ Content-Type: application/json
 { "agent": "support", "session_id": "web:8f3c…", "message": "cadê meu pedido?" }
 ```
 
-The reply is SSE on that same connection — four frame types, and an unknown one is
+The reply is SSE on that same connection — five frame types, and an unknown one is
 safe to ignore:
 
 ```
-event: delta     data: {"delta":"Seu pedido "}     the answer, token by token
+event: delta     data: {"delta":"Seu pedido chegou."}  the published answer
 event: working   data: {"name":"order_status"}     a tool is running
+event: ui        data: {"component":"product_cards","title":"Chocolate","items":[{"id":"SKU-1","url":"https://shop.example/1","caption":"Dark chocolate"}]}
+                                                   a presentation tool picked cards to show
 event: done      data: {}                          the turn ended
 event: error     data: {"message":"…"}             it ended badly
 ```
 
+The shipped widget renders `ui` as a plain list of caption + link under the
+conversation (only an `http(s)` url becomes a link; any other scheme renders as
+text); a host page that wants real cards restyles or replaces that — the
+protocol is the frame. An empty selection sends `items: []`. Unlike `/v1/responses`,
+the web frame omits `count` and `dropped`. See [presentation tools](TOOLS.md#presentation-tools-the-model-picks-ids-the-engine-shows-the-cards).
+
 **The engine issues the session id and the client never proposes one.** `POST
 /messages` with an id nobody minted is a `404`, never a new conversation: on an
 anonymous endpoint, create-on-write means anyone who guesses an id can read someone
@@ -315,6 +323,15 @@ stays internal unless the agent opts in. That contract is
 [the edge contract](ARCHITECTURE.md#what-crosses-the-edge), and it is why you can
 forward `content` straight to the customer.
 
+The last balloon may also carry `attachments`: objects with `type`, `url`, `caption`
+and an optional `id`,
+the cards an evidence tool returned (see [Evidence](TOOLS.md#evidence-the-lean-envelope-and-grounding)).
+When the turn called a **presentation tool**, the list is exactly the cards the model
+selected, in call order, each also carrying the `component` and `title` of that call;
+otherwise it is every card the turn's evidence tools returned. An empty presentation
+selection suppresses that automatic fallback. Ignore the key if the consumer only
+supports text.
+
 ### Delivery policy
 
 A relay declares **how the outbox flushes** — a property of the surface

data/docs/CONTEXT.md

@@ -23,6 +23,7 @@ into a deterministic prompt:
 | Provider | Block | Priority | Layer | Notes |
 |----------|-------|:--------:|-------|-------|
 | **Identity** | system | **100 — pinned** | identity | The agent's prompt files (global system files first). Never cut. |
+| **Fence notice** | system | **99 — pinned** | identity | Fixed instruction to treat contextual material as data; only with `fencing` on. |
 | **Skills** | `<available_skills>` | 80 | identity | Level-1 skill list, minus whatever is already eager — see [Skills](SKILLS.md). |
 | **Tool search** | `<available_tools>` | 70 | identity | Level-1 list of deferred tools — see [Tools](TOOLS.md). |
 | **Skill trigger** | `<active_skill>` | 85 | volatile | Level-2 bodies: the agent's `skills_eager` set, plus the ones whose `triggers:` match the message — see [Skills](SKILLS.md). |
@@ -106,10 +107,10 @@ budget first.
 With `memory` enabled, an agent gains a built-in `remember` tool for durable
 facts, and those facts (plus recent notes) are injected back into the prompt on
 later turns — **including turns in a different session**. Memory is scoped per
-agent, per `(tenant, customer)` when the message carries a `customer`, and per
-session otherwise — a session's own memory lives in a marked `memory:chat:<session id>`
-cell, never a bare one, so the Customers drill cannot read a conversation as a
-customer. This is distinct from *session history*, which is the transcript of one
+`(tenant, customer)` when the message carries a `customer`. Without a customer,
+it uses the tenant's cell; without either, it uses the session's marked
+`memory:chat:<session id>` cell. A fresh session therefore does not isolate
+memory when it still carries the same tenant. This is distinct from *session history*, which is the transcript of one
 conversation; memory is the small set of facts that should outlive any single
 conversation. Facts and notes are editable from the Studio agent page. See
 [`examples/memory/`](https://github.com/guizaols/insika/tree/main/examples/memory/) for a runnable cross-session example.
@@ -174,7 +175,7 @@ Attention is strongest at the end of the context: a goal stated only at the top
 is the first thing a 30-call turn forgets. So the recitation was **moved** there,
 not copied — the head never repeats it, and the turn pays for it once. It rides
 as a `user` message, like every other engine append inside a turn, so the system
-prefix stays byte-stable and the cache breakpoint at its end keeps hitting.
+identity prefix stays byte-stable.
 
 The `still missing` list is the point: the *model* sees which declared fields are
 still unanswered, so it stops re-asking for something already given. Stored keys
@@ -194,17 +195,21 @@ turns and resumes — a resumed conversation re-opens with the briefing intact.
 
 ## The provider prefix cache
 
-Two distinct caching mechanisms — don't conflate them:
+A stable prefix makes provider caching possible; eligibility, expiry and reported
+savings still depend on the provider.
 
-- **Automatic server-side prefix cache.** Some providers prefix-cache a stable
-  system prefix automatically, at no cost to configure. This works **only because**
-  the engine renders the system in two layers (below) and the volatile half sits
-  **under** the identity boundary, keeping the cacheable prefix byte-stable.
-  Anything that injects volatile content high in the system block breaks the cache.
-- **Manual cache breakpoints (opt-in).** With `prompt_caching` on **and** a
-  provider that supports explicit cache control, the builder sets one cache
-  breakpoint at the end of the system block. Only enable this for a byte-stable
-  system — a volatile system turns every turn into a paid cache *write*.
+- **Automatic prefix caching** needs no Insika flag. The identity-first render
+  order keeps changing memory and request data below the stable prefix.
+- **Explicit cache breakpoints** are opt-in via `"prompt_caching": true` on
+  the agent profile and applied only when the resolved provider is `anthropic`. With both system layers present,
+  Insika sends two text blocks: identity with `cache_control`, then volatile text
+  without it. With no volatile text there is one block; with no identity there is
+  no breakpoint. Other providers receive a plain system string.
+
+Custom context builders and hooks must keep `system_identity`, `system_volatile`
+and their joined `system` consistent. Without a split, or after a hook replaces
+only `system`, the chat builder falls back to treating the whole system as identity.
+That fallback cannot protect a volatile suffix from cache invalidation.
 
 Cache accounting surfaces as `cached_tokens` (reads) and `cache_creation_tokens`
 (writes), visible in telemetry and the Studio tokens chip.
@@ -215,13 +220,14 @@ The system block is partitioned into two cache layers:
 
 - **Identity** — bytes that change only on deploy/config edit: the persona
   prompt (`Prompt`), the level-1 skill list (`Skill`) and the deferred-tool
-  catalog (`ToolSearch`). This is the cacheable prefix.
+  catalog (`ToolSearch`), the fixed tool-discipline instructions and, when enabled,
+  the fencing notice. This is the cacheable prefix.
 - **Volatile** — bytes that may change per turn: memory, session history,
   triggered skill bodies, the `<request_context>`. Everything else.
 
 The layer is a **provider-class contract**, not profile data: `ContextProvider`
 declares `def layer = :volatile` (conservative — nothing gets pinned by
-accident) and the three identity builtins override to `:identity`. A pack does
+accident) and the identity providers override to `:identity`. A pack does
 not set it — a pack reorganizes *which content goes into the Prompt provider vs
 the volatile providers*. The Builder stamps the layer on every fragment at
 production, and the render order is **identity first, volatile after** — a
@@ -236,13 +242,14 @@ output must be byte-stable across turns).
 
 ### The observable cache: fingerprints and the invalidation reason
 
-Each turn, the Executor hashes the rendered prefix into a PII-free fingerprint
-chain — one SHA-256 per system category in render order, one for the tool
-schemas, one cumulative `prefix` — and compares it against the previous turn's
-entry. The **invalidation reason** is the first category whose bytes changed (or
-vanished); a turn whose prefix held reports nothing. History is deliberately
-excluded: a new user message is a divergence every turn, which would be noise,
-not a reason.
+Each turn, the Executor hashes the rendered identity and tool schemas into
+SHA-256 fingerprints and a cumulative `prefix`. The invalidation reason names
+the first changed part of that stable prefix. Volatile system categories have
+separate diagnostic digests: changes to memory, knowledge or request context do
+not report an identity-prefix invalidation. History is excluded.
+
+These fingerprints explain local prompt changes; they do not prove a provider
+cache hit. Use the provider's token accounting for that.
 
 The Studio surfaces it in two places: the **session Context card** shows the
 turn's cache-hit percentage and the `broke: <category>` line (plus the
@@ -251,9 +258,8 @@ cache tab with the per-agent hit series over time. The per-agent series lives
 in its own capped store, because a session does not stamp its author — the
 per-session trace cannot answer "cache-hit over time for *this* agent".
 
-With the prefix stable by construction, the existing `prompt_caching` breakpoint
-sits on bytes that stay put — the first (write) turn of a deployment pays the
-cache write once, every subsequent turn reads.
+A stable identity can be reused while the provider cache remains eligible and valid.
+A changed tool schema still invalidates the local prefix fingerprint.
 
 ## The volume