insika 0.7.0 → 0.9.0

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/ARTIFACTS.md

@@ -67,6 +67,48 @@ No script, no external fetch, no forms. The model writes HTML with **inline
 SVG** for charts — that is a skill instruction (palette, tables, pure-SVG bars),
 not engine code. A "real" charting need is a plugin.
 
+## Reasoning effort on a report turn
+
+A report turn is not one shape of work — it plans, then it mines, then it
+writes. `thinking` is one value per agent for the whole turn, so an agent set to
+`high` pays deliberation on every one of the 30–50 tool calls a real report
+makes, and that is where the 300 s turn timeout gets spent.
+
+Split the phases across agents instead, which the engine already supports today:
+
+```ruby
+Insika.system do
+  # The miners: one narrow question each, no judgement to make.
+  agent("sales_miner") do
+    model "deepseek-v4-flash"
+    params thinking: "low"
+    tools %w[query_sales]
+    instructions "Answer ONE question about sales from the store data. Numbers, no prose."
+  end
+
+  # The orchestrator: it plans the report and writes it. This is the turn
+  # that deserves the deliberation.
+  agent("reporter") do
+    model "deepseek-v4-flash"
+    params thinking: "high"
+    tools %w[save_artifact]
+    subagents "sales_miner"
+    instructions "Plan the report, call spawn_subagents ONCE for every number you need, then write the page and save_artifact it."
+  end
+end
+```
+
+Two things make this work: a child inherits the *environment* (model, thinking)
+only as a **default**, so its own `params thinking:` wins; and `spawn_subagents`
+runs the children in parallel, so wall-clock is the slowest miner rather than
+the sum. Each child also mines in its own isolated context, which is what keeps
+the orchestrator's context from filling with raw rows.
+
+Measure it before reaching for anything cleverer: the numbers that matter are
+the turn's wall-clock, the timeout rate, and the judge score on the same report.
+Per-phase effort *inside* a single turn is a real idea, but it is only worth
+building once this recipe is shown not to be enough.
+
 ## Limits and retention
 
 - **Size cap** — `INSIKA_ARTIFACT_MAX_BYTES` (default 1 MB): an artifact is a

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,14 +23,16 @@ 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). |
 | **Knowledge** | `<knowledge>` | 77 | volatile | Level-1 top-K learned concepts for the turn's message (+ one-hop `[[links]]`), only if `knowledge.retrieve` is on. Cuttable — see [Knowledge](KNOWLEDGE.md). |
 | **Memory** | `<memory>` | 75 | volatile | Durable facts + recent notes, only if `memory` is on. Cuttable. |
-| **Briefing** | `<briefing>` | 65 | volatile | The session's working state (known fields, still-missing list, next step) — only if the pack declared `briefing_fields`. Cuttable. |
+| **Briefing** | `<briefing>` | 65 | volatile | The session's working state — the *known* fields only. Only if the pack declared `briefing_fields`. Cuttable. |
 | **Session** | history | 60–79 | volatile | The running transcript; priority scales with recency. |
 | **Request** | `<request_context>` | 40 | volatile | Turn variables + tenant. Most cuttable; sits last. |
+| **Briefing (tail)** | `<recitation>` | 95 | volatile | The still-missing list + next step, rendered **after the whole history** as a `user` message — the last thing the model reads before the current message. |
 
 The ordering is deliberate: the render order is **identity layer first, volatile
 layer after** — nothing volatile can sit above the cache boundary, whatever its
@@ -53,14 +55,37 @@ cacheable prefix byte-stable (see the prefix cache below).
 > returns empty turns, raise `context_budget` (e.g. to `60000`) before looking
 > anywhere else. See [Agents](AGENTS.md#default-limits).
 
-### Compaction is not wired — except the mechanical dedupe
-
-There is a settings stub for LLM-summarization compaction (`enabled: false`,
-`keep_last`, a reserved utility-model slot), but **nothing consumes it today**
-— and the Studio no longer shows a form for it, so the setting cannot be
-switched on by accident. Size is managed purely by hard budget eviction.
-Do not rely on compaction to shrink a bloated agent: tune `context_budget` and
-keep the identity lean.
+### In-session compaction (opt-in, platform Settings)
+
+When enabled (Studio → Settings → General, or the `compaction` settings hash),
+the engine summarizes old turns *inside* the session instead of losing them to
+eviction:
+
+- **Trigger:** after a turn commits, if the session's *uncompacted* message
+  count exceeds `compact_after` (default 40), everything but the last
+  `keep_last` messages (default 20) is summarized by a cheap model
+  (`compaction.model`, falling back to the platform `utility_model`; neither
+  set = the feature is inert and `insika doctor` warns). Runs off the critical
+  path — the customer already has the answer.
+- **Read path:** the Session provider replaces the compacted prefix with ONE
+  history fragment — a `user` message wrapped in `<conversation_summary>` tags,
+  priority 59 (one step below the oldest verbatim message), source
+  `compaction` (its own category in the context trace). The tail stays
+  verbatim and the boundary is **stable** between compactions, so the prompt
+  cache holds after it.
+- **What survives:** the default prompt orders the summary to preserve customer
+  facts (sizes, CEP, order numbers), the assistant's commitments, the still-open
+  questions and the decisions already made; on re-compaction the previous
+  summary is folded in, so a fact from turn 3 survives every later batch.
+  A platform `compaction.prompt` replaces the default wholesale.
+- **Scope:** store-sourced history only — a checkpoint resume replays its own
+  tape and an explicit `history` is the caller's contract; neither is
+  rewritten. Observability: the `:context_compacted` event, the
+  `insika.context.compacted` counter and `{upto, runs}` in the context trace.
+
+Compaction does not replace the budget: eviction stays as the hard backstop
+for a single oversized turn. Tune `context_budget` and keep the identity lean
+regardless.
 
 One cheap half **is** wired, opt-in per agent: `tool_output_compression` (DSL
 `tool_output_compression`, or `"tool_output_compression": true` in the pack).
@@ -82,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.
@@ -121,19 +146,37 @@ pack:
 briefing_fields "size", "budget", "delivery_day"
 ```
 
-With fields declared, the turn's `:system` context gains a `<briefing>` block
-(priority 65 — below identity/skill/memory so it never breaks the cacheable
+With fields declared, the briefing renders in **two places**, and the split is
+deliberate.
+
+The durable half — what is already known — sits in the `:system` context
+(priority 65: below identity/skill/memory so it never breaks the cacheable
 prefix, above the turn's own `<request_context>`):
 
 ```
 <briefing>
 known:
   size: M
+</briefing>
+```
+
+The half that is a *goal* — what is still missing and the agreed next step — is
+**recited at the tail**, after the whole history, as the last thing the model
+reads before the current user message:
+
+```
+<recitation>
 still missing: budget, delivery_day
 next step: send the payment link tomorrow at 10
-</briefing>
+</recitation>
 ```
 
+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
+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
 that the pack no longer declares are never rendered. The Studio session screen
@@ -152,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.
@@ -173,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
@@ -194,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
@@ -209,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
 

data/docs/DEPLOY.md

@@ -25,7 +25,7 @@ is durable SQLite (WAL) at `INSIKA_DB`; mount a volume and point it inside.
 docker build -t insika .
 docker run -p 9292:9292 -v insika-data:/data \
   -e DEEPSEEK_API_KEY=sk-... \
-  -e OPENCLAW_GATEWAY_TOKEN=change-me \
+  -e INSIKA_GATEWAY_TOKEN=change-me \
   insika
 curl localhost:9292/up      # {"status":"ok"}
 ```
@@ -115,7 +115,7 @@ this section is the single source of truth for what changing it means.
 | `INSIKA_DRAIN_TIMEOUT` | `20` | seconds a stopping worker waits for in-flight turns before abandoning them to the next boot's recovery (process model, item 4). The entrypoint sizes Falcon's `--graceful-stop` from it; on Railway also set `RAILWAY_DEPLOYMENT_DRAINING_SECONDS` ≥ drain + 10 |
 | `INSIKA_TICK_INTERVAL` | `60` | seconds between tick passes — outbox drain + stale recovery sweep (process model, item 5). `0` disables |
 | `INSIKA_TICK_STALE_AFTER` | `900` | seconds a `:queued`/`:running` task must sit untouched before the tick sweeps it. Must exceed the largest `turn_timeout` of the deployment |
-| `OPENCLAW_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for `/v1/responses` and `/v1/agents` (the API contract) |
+| `INSIKA_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for `/v1/responses` and `/v1/agents` (the API contract) |
 | `ADMIN_TOKEN` | `local-demo` | login token for `/studio` (**change in production**) |
 | `DEEPSEEK_API_KEY` | — | provider key. **Without it the engine still boots** (`/up` green), but turns fail until it is configured (env or Studio → LLM providers) — cloud resilience |
 | `DEEPSEEK_MODEL` | `deepseek-v4-flash` | model |
@@ -157,7 +157,7 @@ values (the API token falling back to `ADMIN_TOKEN` is a dev convenience only):
 - **`ADMIN_TOKEN`** — the `/studio` login (cookie auth). This is the **operator**
   surface (just you). Rotating it is **safe and independent**: change it, redeploy,
   log in with the new value. It does not affect any API consumer.
-- **`OPENCLAW_GATEWAY_TOKEN`** — the Bearer for `/v1/responses` and `/v1/agents`.
+- **`INSIKA_GATEWAY_TOKEN`** — the Bearer for `/v1/responses` and `/v1/agents`.
   This is the **contract with your API consumers**. Rotating it means **changing
   both sides together** (or the integration breaks): update the runtime var **and**
   each consumer's token in the same step.
@@ -187,15 +187,35 @@ insika doctor            # colored report; exits != 0 on any error
 insika doctor --json     # machine-readable (CI / monitoring)
 insika doctor --fix      # applies the safe autofixes and re-diagnoses
 insika env               # lists known keys + current values (secrets masked)
+insika tools:report      # tool audit over the stored traces: never-called
+                         # allowlisted tools, error rate > 30%, stale tools, gate refusals —
+                         # read-only, the operator removes ([--agent ID] [--days N] [--json])
 ```
 
 Checks: env (the schema above), settings schema version (a pending migration →
 `--fix` applies it), a missing platform `default_model` (`--fix` seeds it from
 `DEEPSEEK_MODEL`), durable vs ephemeral backend, LLM provider configured,
-`ADMIN_TOKEN` set, data-tool definitions still valid, **prompt files that hold
+`ADMIN_TOKEN` set, data-tool definitions still valid, **a stored agent whose
+declared tool allow/deny list does not name the `tool_allowlist` policy** (the
+engine repairs it on read, but as stored the list is inert — see
+[Agents](AGENTS.md#the-allowlist-convention)), **prompt files that hold
 text rather than a serialized object** (a file whose content is a stringified Hash
 serves a mangled prompt on every turn while looking perfectly healthy — present,
-non-empty, and the agent still answers), and **skill drift** — a shared skill whose
+non-empty, and the agent still answers), **a prompt file that outgrew a prompt**
+(WARN past ~6 000 estimated tokens or 600 lines — the LLM-generated pack shape
+that costs 20%+ extra tokens per turn for no better instruction-following),
+**in-session compaction enabled with no model slot** (WARN — neither
+`compaction.model` nor the platform `utility_model` is set, so it can never run;
+see [Context](CONTEXT.md)), **eval seeding left on** (WARN — `evals.seeding`
+opens `POST /v1/conversations/:id/seed`, which writes a fabricated conversation
+state under the tenant token; fine while running snapshot evals, off in
+production — see [Evals](EVALS.md#state--a-case-starts-from-a-snapshot)),
+**provenance and presentation tools without an allowed evidence data tool**
+(WARN — the check only sees stored data declarations; verify any code-tool source),
+**fencing off for agents exposed by relay/widget environment configuration**,
+**cache-layer declarations** (known volatile providers marked identity are errors;
+custom identity providers need a byte-stability review), and
+**skill drift** — a shared skill whose
 body names one store, a prompt file routing to a skill the agent cannot load, a broken
 companion pair, a stale `eager:` key (see
 [Skills](SKILLS.md#drift-guards)). Settings-schema migrations are **explicit**
@@ -227,7 +247,7 @@ healthcheck, and a restart policy.
 2. **Volume**: mount it at `/data` (the default `INSIKA_DB` points there) —
    without a volume, SQLite is ephemeral and recovery resumes nothing after a
    redeploy.
-3. **Vars**: `DEEPSEEK_API_KEY`, `OPENCLAW_GATEWAY_TOKEN`, `CONSUMER_INTERNAL_URL`,
+3. **Vars**: `DEEPSEEK_API_KEY`, `INSIKA_GATEWAY_TOKEN`, `CONSUMER_INTERNAL_URL`,
    `INSIKA_EGRESS_HOSTS`. **Leave `WEB_CONCURRENCY` at its default of 1** unless
    you run [`insika-router`](ROUTER.md) in front. Railway's own docs say it
    "does not support sticky sessions" and randomly distributes traffic across
@@ -402,7 +422,7 @@ cache hits, P50/P95, error rate. Runs against local or a remote deployment. See
 [LOADTEST.md](LOADTEST.md).
 
 ```bash
-INSIKA_URL=http://localhost:9292 OPENCLAW_GATEWAY_TOKEN=xxx \
+INSIKA_URL=http://localhost:9292 INSIKA_GATEWAY_TOKEN=xxx \
   bundle exec ruby scripts/loadtest.rb --agents assistant --concurrency 16 --iterations 3
 ```
 

data/docs/EVALS.md

@@ -42,6 +42,99 @@ expect:
 Turns replay **in order** under one conversation, so a case can build context ("what
 about the shipping?" after "I want the 70% bar"); the assertions run on the last turn.
 
+### State — a case starts from a snapshot
+
+Every case above starts from an **empty** conversation. To test "the customer already
+saw three products and says *add the second one*", such a case would first have to
+replay the search turn — which makes it depend on the model's first answer, costs a
+turn, and cannot reproduce a messy state (a contradiction from six turns ago, a
+stored preference). `state:` is the precondition, loaded into the conversation
+**before turn 1**:
+
+```yaml
+id: loja-chocolates-add-seen
+agent: loja-chocolates
+requires:
+  tools: [add_to_cart]
+state:
+  evidence:
+    ids: ["SKU-70-DARK"]
+    cards:
+      - { type: card, url: "https://shop.example/70", id: "SKU-70-DARK", caption: "Dark chocolate" }
+  memory: { facts: { preference: "dark chocolate" }, notes: [] }
+  history:
+    - { role: user, content: "quero chocolate amargo" }
+    - { role: assistant, content: "O chocolate 70% é SKU-70-DARK." }
+  briefing: { fields: { cep: "01311-000" } }
+turns:
+  - user: "adiciona uma unidade desse chocolate 70% no carrinho"
+expect:
+  tools_called: [add_to_cart]
+  never_calls: [search_products]
+  reply_omits: ["SKU-70-DARK"]
+```
+
+Only those four `state` keys are accepted by the case loader. A persona case may
+carry `state` too. Adapt the tool names, arguments and briefing fields to the agent.
+
+The evidence ledger is a runtime precondition, not a list shown to the model:
+include the relevant product and ID in `history` or the user's request. `cards`
+seeds the cards a search would have returned (each needs a `url` and an `id`; the
+id counts as seen), so a presentation case needs no lookup in the turn.
+
+With the HTTP transport, the eval stays a **client**: the runner never writes a
+store. Seeding goes through
+`POST /v1/conversations/:id/seed` (same Bearer as the turn, same id namespacing for a
+tenant), and the deployment accepts it **only while the platform setting
+`evals.seeding` is on** — off by default, because a seeded conversation is a
+fabricated precondition, and the doctor warns while it is on. With the setting off
+the replay Runner **skips** seeded cases with a reason; it also skips when its
+transport has no seed support. Other seed errors fail the replay. In-process
+`GraphTransport` dispatches `seed_session` directly and bypasses `evals.seeding`;
+it needs a runtime exposing the graph. The persona
+Simulator surfaces seed refusal as an error instead of the Runner's skip result.
+
+A session with messages returns `409`. Replays default to `eval-<case-id>`; pass
+`--conv-map FILE` with a JSON mapping such as
+`{"loja-chocolates-add-seen":"eval-add-seen-run-2"}` to use a fresh ID on reruns.
+Seeded memory may share a tenant cell even with fresh IDs; see
+[the seed API](API.md#seeding-an-eval-conversation) for scope and payload details.
+
+#### Graders — what a turn's calls and reply are checked against
+
+The turn's SSE stream reports each tool call with its arguments and how it ended
+(`ok`, `error`, or `blocked` plus the gate that held it), so the deterministic
+layer can check more than "was the tool called". All optional; each is its own
+check, and the report names the one that failed.
+
+| Key | Checks |
+|-----|--------|
+| `tools_called: [name, name?]` | each required tool was called (`?` = optional, never fails) |
+| `never_calls: [names]` | none of these was called — the negative every `tools_called` needs |
+| `calls_one_of: [names]` | at least one of these was called |
+| `first_tool: name` | the first call's name |
+| `max_tool_calls: N` | a ceiling on the turn's calls |
+| `reply_includes: [substrings]` | each appears in the published answer (case-insensitive) |
+| `reply_omits: [substrings]` | none appears — where an internal id, a CPF or a raw tag leaking into the customer's text is pinned |
+| `blocked_gates: ["tool:gate"]` | each pair appears among the turn's blocked calls |
+| `ui_components: [names]` | a presentation tool showed at least one card of each component (the `insika.ui` frames) |
+| `no_ui: true` | the turn showed nothing — the negative of `ui_components` |
+| `must_not: [detectors]` | the negative detectors (`pii_leak`, `tool_error`, …); a blocked call is not a tool error |
+
+**Every positive has a negative.** A case that only says `tools_called: [add_to_cart]`
+passes an agent that also re-searched, or that echoed the SKU to the customer. Pin
+what a correct turn does *not* do — `never_calls`, `reply_omits`, `max_tool_calls` —
+in the same case. Snapshots avoid the model calls needed to reconstruct the setup;
+use the simulator when later customer messages need to branch on the replies.
+
+`tools_called` confirms an attempted call, not a successful backend mutation.
+Arguments are collected for inspection; there is no generic argument or cart-state
+grader. `blocked_gates` needs completion statuses from the HTTP transport. The
+in-process `GraphTransport` records tool names and UI events, but not completion
+statuses or arguments. Neither transport counts `load_skill` / `load_knowledge` as
+tool calls. `ui_components` requires a nonempty selection; `no_ui`
+accepts absent UI events and events with zero items.
+
 ### `requires` — a case that cannot run here is skipped, not failed
 
 Deployments differ. Some stores have order tracking wired, some do not; some run
@@ -269,14 +362,11 @@ The model only sees `case_id`, enumerated with the ids the tool can actually run
 (never a free string it could invent) — every **simulated** case in the store, the same
 `persona:` shape as above.
 
-**Safety is derived here too, but there is no swap yet.** The tool computes the
-target's reachable side-effect tools (`Evals::EvalProfile`, the same derivation the CLI
-uses) and **refuses outright** — naming the tools — if that list is non-empty. Unlike
-the CLI, nothing here actually swaps a side-effect tool for a dry-run: `Evals::
-EvalProfile.registry` (the overlay) exists for exactly that, but nothing calls it yet.
-So `run_persona_eval` only runs against **read-only** target agents today; wiring the
-overlay into an in-process turn (so a target WITH a write tool can be tested safely) is
-follow-up work, not something this tool claims to do.
+**Side effects are replaced for local graph runs.** The tool derives the target's
+reachable side-effect tools and builds a throwaway executor with recorder tools
+under those names. Read-only tools and the other graph collaborators are shared.
+If side effects are reachable but no graph was supplied, it refuses the run.
+This substitution prevents real writes; it does not prove a backend mutation.
 
 **Budget**: the persona model + judge model calls are the cost of running the eval,
 charged to the **calling** agent's own turn — never the target's (the target's own