insika 0.9.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec89eb1dae94e5a57733d0dd88a19d92ff98eb7e2ae0b907792e2a4ce8d508aa
-  data.tar.gz: cb882c8015e00c0c905e5945a05a5a465c938dedda762914c3737a64a9f0d4fb
+  metadata.gz: b98a9d84df7cda373881cc11d0658bc3dd208ceb4bc52c23ed4fed4bd641fbb4
+  data.tar.gz: cecc0e4671a335efc5670f297aaf53ebafd5f1662f25a3121894825582494b30
 SHA512:
-  metadata.gz: e2acb07f2ae896ee762cd3f1113dca3d462f80ea0bb32caea69f5db3fd6fbd31821cf9a5140b32c64c26b702b29b78aaf9fec0ca8f59653178dcb37afe9eca38
-  data.tar.gz: f8c98a2b76c802a75e18a77e0762ef42c650aa956afb3f131e1e9ccacfb2a56de87540b7389c740021008b45a174fa371d7a6dbb0a5a7cf83f248ce41b696770
+  metadata.gz: 332d1cea74cdbee9e3241dfefc73538824643fe3b65964fb2584ed57fb4d85c7b1cb547c7d2ccf3ff2acd4893d49063bed60fbf6e94ed6968e1c30bbd9671b30
+  data.tar.gz: d203a16b2954fb36829ed074a463ebac6dce26fea980e546debf5e908e4bf6bfb77c7d04b2e703816254022eaf3da9dbbce1a09c845525454dc6126996ce00b0

data/CHANGELOG.md

@@ -3,11 +3,246 @@
 All notable changes to this project are documented here.
 
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the
-project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once
-it is released. Entries land with the pull request that makes the change.
+project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) from 1.0.0 on. Entries land with the pull request that makes the change.
 
 ## [Unreleased]
 
+## [1.0.1] - 2026-10-23
+
+### Removed
+
+- Internal planning notes (`docs/superpowers/`) are no longer in the repository or the
+  gem. 1.0.0 shipped them by mistake; the packaging now never ships that directory.
+
+## [1.0.0] - 2026-10-23
+
+### Added
+
+- Harvest page: each pending or blocked candidate shows its skill text, rationale and origin conversation; a blocked one can be re-gated once the missing piece is fixed; the page says when the loop skips an agent (harvest off, or no grounding matcher).
+- Studio screens for watching conversations and what waits on a person (see
+  [Studio](docs/STUDIO.md)):
+  - **Live** (`/studio/live`): one card per recent conversation, moved by the
+    event stream (tools in the running turn, "agent is writing…", guardrail
+    flags), with an event ticker. `?agent=` shows one agent's conversations.
+  - **Why this reply**: under each agent reply, its turn's context by category,
+    skills injected and why, tool calls with timing and guardrail flags, plus
+    Replay in Playground and Save as eval case.
+  - **Inbox** (`/studio/inbox`): approvals, fact proposals, mined skills,
+    refinement runs and guardrail false-positive reports in one list, oldest
+    first, with tabs per type.
+  - **Guardrail false positives**: a flag can be marked as a false positive,
+    then resolved or undone (`:review_guardrail_flag`). The verdict lives on the
+    flag inside the session.
+  - **Agent History**: outcomes per day over 30 days with a marker per change
+    to a prompt file or to the agent's own skills, and per change a short diff
+    and the outcomes 7 days after vs 7 days before.
+  - **Funnel drops**: the biggest loss between stages, and per loss the
+    conversations that stopped there, grouped by the last thing that happened.
+  - Chats tabs (All / Active now / Guardrail flagged), a customer card on the
+    session, a tool-call waterfall per turn, an Overview "Needs attention" row,
+    a `⌘K` palette, and a sidebar grouped as Operate / Review / Build /
+    Insights / Platform with a count badge on each Review page.
+  - Markup tags in message text (`<carrossel/>`, `<vitrine formato="lista">`)
+    show as highlighted tokens, escaped and never rendered.
+- `Store#amend(scope, key, value)`: overwrites a key without moving it in
+  `#recent`. The default is `#set`; a backend whose `#recent` follows its own
+  write order overrides both (the contract suite checks it). Memory, SQLite and
+  Postgres implement it.
+- Persisted turn messages and tool-call traces carry `task_id`, so the Studio
+  ties each message to its own turn.
+
+- `scripts/migrate_openclaw.rb seed`: carries recent OpenClaw conversations into
+  Insika sessions (`POST /v1/conversations/:id/seed`) so a returning customer
+  keeps the context. Reads root and per-process SQLite transcripts, follows the
+  active branch from the last compaction, keeps only customer text and agent
+  replies, and skips conversations that already have messages. `--only`/`--as`
+  rehearse one conversation on a test chat.
+  Each session is stamped with `--agent`, so the Studio lists it under that
+  agent; re-running stamps sessions seeded before (they still answer 409).
+- Platform agent defaults (Studio › Settings › Agent defaults, or
+  `update_settings` with `agent_defaults`): an agent with no value of its own
+  for reliability, knowledge, memory retrieval, budget, alerts, guardrails,
+  grounding, follow-ups, distillation or harvest runs with the platform's. The
+  agent's own value wins whole. Each of those sections in the agent config has
+  a "use the platform default" box; saving with it checked keeps the agent
+  inheriting. A default is validated on save, and one that stops building
+  later leaves agents on their own values instead of failing turns. Agents
+  saved in the Studio before this have their own knowledge, guardrails,
+  distillation and harvest values (the form always wrote them): check the box
+  to make them inherit.
+
+- **Optional Postgres store** (`INSIKA_DATABASE_URL`, `INSIKA_DATABASE_POOL`). It passes the
+  same store contract as SQLite; `pg` is not a gem dependency and loads only when the
+  variable is set. `scripts/store_copy.rb` moves an existing store. See
+  [Postgres store](docs/DEPLOY.md#postgres-store-optional) for when it pays off.
+- `Store#entries` and `Store#recent`: a whole scope, or its most recently written keys, in
+  one call. The default implementation keeps third-party backends working; SQLite and
+  Postgres answer each in one query. The Studio's session and task lists use them.
+- `INSIKA_SLOW_STORE_MS` also logs each slow write batch: its size, bytes, scopes, and how
+  long it waited for the lock versus how long its commit took.
+
+### Changed
+- Session stats are versioned (`"v" => 2`, adds the guardrail flagged and
+  reported counts). `scripts/backfill_session_stats.rb` now also rewrites stats
+  older than the current version, not only missing ones.
+- Reviewing a guardrail flag no longer moves the session to the top of the
+  recent lists.
+- **MCP tools are named after their instance**: `<instance>__<tool>` (e.g.
+  `shop_staging__list_products`). Two instances offering the same tool used to share
+  one name, and every call went to whichever instance came first. Agents that allowed
+  MCP tools by name must select them again; per-tool overrides keep the server's name.
+- `INSIKA_EGRESS_HOSTS` pins an MCP server only when its host resolves to a private
+  address. The operator registers the URL and the model cannot change it, so adding a
+  public server needs no redeploy. HTTPS still applies, and a private server still needs
+  `INSIKA_EGRESS_ALLOW_PRIVATE` and a listed host.
+
+- An input guardrail injection hit no longer replaces the turn with the canned
+  refusal by default. The message reaches the model with a per-turn
+  `<security_notice>` (never persisted) and an audit `guardrail_flagged` with
+  `action: "flag"`, so a legitimate request in the same message is still served.
+  Sexual and abuse hits still block, now also when the message carries an
+  injection too. `guardrails.injection: "block"` (Studio › Guardrails › on
+  injection) restores the old behavior.
+- `Store#recent` takes an optional fourth argument, `offset`, to read the next page; a
+  backend that implements the three-argument form keeps working (the stores pass
+  `offset` only when paging). SQLite reads a page's keys from the index and then only
+  their values, instead of reading every value in the range to sort it.
+- Studio: the tasks list shows 50 tasks per page, newest first, instead of every task.
+  The home reads only the sessions of the last 14 days; its messages card counts that
+  window (and says so), and the conversations total comes from the keys alone.
+- Every session write also writes a small stats record (last update, message count,
+  agent) in the `session_stats` scope, and the Studio home reads those instead of whole
+  sessions (every stat, filtered by date, so the order they were written in does not
+  matter). Sessions stored before this change have no stats until
+  `scripts/backfill_session_stats.rb` runs once (idempotent, safe with the app running;
+  it also removes stats whose session is gone).
+- RubyLLM is pinned to a newer `2.0.0` commit: streamed responses are priced once when
+  read instead of on every chunk, and HTTP connections are shared per process and
+  settings. Specs stub LLM HTTP with `stub_llm_http`, because swapping the adapter on an
+  already-built connection no longer takes effect.
+
+- Studio tools are grouped by origin and MCP server, with name/server filtering,
+  collapsible sections and per-section select/deselect actions. Selection keeps
+  denied tools blocked and requires saving before permissions change.
+
+- Workflow and tool argument validation now use JSONSchemer. Explicit nulls and
+  declared constraints are enforced; existing tool scalar leniency remains.
+- Distillation, harvest, knowledge and refinement use native structured responses.
+  Retired MCP import delegates to live discovery instead of generating HTTP snapshots.
+
+- RubyLLM 2 migration: native loop control, tool schemas, cache markers, and usage
+  readers. MCP now uses the native RubyLLM client, replacing `ruby_llm-mcp` and the
+  Origin-header patch. Legacy SSE requires migration to Streamable HTTP. See
+  [migration results](docs/RUBYLLM_2_MIGRATION.md).
+- Requires RubyLLM `~> 2.1` from RubyGems; the Git pin is gone. A provider's 400
+  quota message ("quota exceeded", "wait before trying again") now arrives as
+  `RubyLLM::RateLimitError` and is retried and rotated instead of failing the turn.
+
+- SQLite writes from concurrent turns share one transaction and one commit (group commit),
+  so N worker processes take the file's write lock far less often. A turn opens and
+  closes its task record in one write each, and skips an empty evidence write.
+- Litestream 0.5 with its blocking checkpoint disabled (`truncate-page-n: 0`); it restores
+  backups made by 0.3.
+- Less CPU per turn: the prompt reads an agent's files once per build, the prompt-echo
+  check caches each squeezed prompt, and streamed events are matched only against their
+  own session's subscriptions.
+
+### Removed
+
+- **The `HARNESS_*` environment variables (breaking).** Only the `INSIKA_*` names are
+  read. A leftover `HARNESS_*` key is no longer honored: it is reported as an error
+  naming its `INSIKA_*` replacement (a warning at boot, fatal under
+  `INSIKA_CONFIG_STRICT`, and an error in `insika doctor`), so a stale `HARNESS_DB`
+  cannot silently boot the engine on the memory backend. `EnvSchema.reconcile_legacy!`
+  is gone, and the bundled `insika-code` plugin and example read `INSIKA_CODE_*`.
+- **The `plugin.yml` manifest name (breaking).** Only `insika.plugin.yml` loads. A
+  leftover `plugin.yml` is not loaded and warns to rename it.
+- `Insika::LLMHTTPAdapter` (`faraday_adapter = :insika_net_http`). RubyLLM 2.1 shares
+  one connection per process and settings, so the stock `:net_http` no longer builds a
+  CA store per chat. A deployment that set `:insika_net_http` drops that line.
+
+### Fixed
+
+- Skills written in one worker (pack import, Studio edit, `write_skill`) now reach the other workers within 2 s. The catalog only reloaded in the worker that handled the write, so the others kept the skills they booted with until a restart — in the Studio and in customer turns.
+- Harvest no longer mines simulator/eval sessions (`sim-…`, `eval-…`), and the miner sees the candidates still open so it stops re-proposing the same idea under new names.
+- Harvest: a bare `miner.model` ref (no `provider/`) now uses the agent's provider; it used to fail every run with `Provider must be specified`.
+- Studio: `/studio` without a trailing slash answered 404; it now opens the
+  Overview.
+- Studio: the agent History chart and arm conversions counted outcome kinds
+  against the primary stage name, so they read 0 whenever the kind and stage
+  names differ; they now map kinds through `advance_on`.
+- Studio: a negative message or flag index on a guardrail review counted from
+  the end and reviewed the wrong flag; it is now not found.
+- An error that is fatal only for one model or account no longer kills the turn:
+  no balance (402), a bad key or missing access (401/403) and a model the provider
+  does not have (404) move straight to the next fallback node — no retry on that
+  node, no backoff, and no circuit-breaker count (an open primary circuit fails
+  fast without rotating). On the last node it still raises; a 400 still never
+  rotates.
+- Studio model fields are type-to-search pickers over the configured providers'
+  `provider/model` refs (their declared models, plus the chat models of key-only
+  providers): the agent model, a new agent, the playground pin and Settings'
+  default, fallback (one slot per position) and utility models. The server
+  refuses a ref outside the list — a typed `openai/gpt-x` under provider `openai`
+  used to reach the API as `openai/openai/gpt-x`. A stored value outside the list
+  is shown marked "not configured" and may be saved back unchanged. The plain
+  `model`/`provider` fields still pass as given for API clients.
+  The same pickers cover the reliability fallback chain (agent and Agent
+  defaults) and the refinement proposers, one slot per position, and the
+  knowledge, distill, harvest-miner and compaction models.
+- Data-tools imported or edited in one worker now reach the others: the tool
+  registry checks the config version token (at most every 2 s) and rebuilds when
+  it moved, and the tool catalog follows. Before, the other workers kept the
+  catalog they booted with until a restart.
+- LLM providers authored at runtime reach every worker process, and survive a
+  restart: each chat re-applies the stored providers when they changed. Before,
+  only the worker that served the edit had the key, so a fallback on that
+  provider failed as unconfigured. A cleared key stops being used; a key from
+  the environment is never cleared by it.
+- Deleting an LLM provider authored at runtime puts back the key and base the
+  process started with (for example from the environment) instead of leaving
+  the provider without credentials; a worker that never applied the provider
+  leaves its config alone. Delete no longer disables a provider that also has a
+  key from the environment.
+- Native chat usage includes tool rounds and retries, and failed turns expose
+  recorded usage. Responses projects cache-inclusive totals; negotiated pricing
+  no longer subtracts cache reads from already non-cached input.
+- Reliability honors session model pins and model allowlists without multiplying
+  its attempt budget by RubyLLM transport retries.
+- Speech response reads stop at the byte limit before buffering the entire body.
+- Workflow schemas accept valid `false` values.
+
+- **A merged fragment is framed by `steer_join`, like a steered one already was.** The
+  two burst doors disagreed on what the model sees: a steered message becomes its OWN
+  `user` message in the transcript (framed by `steer_join`), while a merged one was
+  concatenated into the queued turn's single payload by a bare `\n`. A burst therefore
+  reached the model as one run-on paragraph with no boundary between the asks, and a
+  trailing constraint could be answered by nothing (staging, Acme Beauty,
+  2026-09-18: five messages merged 4/4, and the answer never mentioned the fifth).
+  `steer_join` now applies to both doors; the default `nil` returns the text untouched,
+  so a wiring that never set it is unchanged.
+
+- **The door is open for as long as a turn is queued, not only during a debounce
+  window.** `collect`/`steer` merged a fragment only while a turn sat in a
+  `debounce_ms` window; a message that arrived while a turn waited behind the one in
+  flight joined nothing and became a turn of its own, third in line. A
+  `POST /v1/messages?stream=false` caller then held its connection through TWO turns
+  and timed out — on the WhatsApp integration that surfaced as a technical apology
+  to the customer, once per excess message of a burst. A queued turn is now mergeable
+  with or without a window, so every burst message answers immediately with `merged`
+  or `steered`. `followup` (the default) is untouched.
+- **Re-importing a pack no longer erases the knobs it did not send.** `limits` and
+  `params` now MERGE per key on an update (`PackImporter::KNOB_BAGS`); everything
+  else keeps replacing. A provisioning client that publishes
+  `limits: {turn_timeout:, context_budget:}` used to drop every other knob on the
+  agent — `queue_mode`, `debounce_ms`, `chat_rate_limit` — so an unrelated playbook
+  publish silently reset the queue policy an operator had set in the Studio. The
+  authoritative allowlists (`prompt_files`/`skills`/`tools_allow`) are unchanged: a
+  name that left the pack still leaves the agent.
+- One door per queued turn: with two turns waiting, the second used to take over the
+  first's fragment count, and the first then ran from a message snapshot the store had
+  already grown past.
+
 ## [0.9.0] - 2026-09-07
 
 The commerce-agent wave: the engine now enforces what the prompt used to ask for —

data/README.md

@@ -16,7 +16,7 @@ web control UI. Point an existing Responses client at it and serve many agents f
 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.
+- **Durable & resumable** — every turn checkpoints; recorded side-effect calls are deduplicated on replay. External writes still need idempotency.
 - **Agents as data** — agents, prompts, skills and tools are editable at runtime (UI or API), no redeploy.
 - **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)).
@@ -139,6 +139,7 @@ navigates by.
 - [Load test](docs/LOADTEST.md) — load-testing and data topology.
 - [Soak](docs/SOAK.md) — the long run that finds what a short one cannot.
 - [Benchmark](docs/BENCHMARK.md) — the neutral, reproducible, provider-free engine benchmark.
+- [Performance](docs/PERFORMANCE.md) — what keeps a turn cheap (fibers, SQLite group commit, memory trim) and what was tried and left out.
 
 **Improve**
 
@@ -178,6 +179,7 @@ and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). Vulnerabilities go through
 
 ## Status
 
-Pre-1.0 — published on [RubyGems](https://rubygems.org/gems/insika); APIs may
-still change between minor versions ([CHANGELOG.md](CHANGELOG.md)). Licensed
+Published on [RubyGems](https://rubygems.org/gems/insika) and follows
+[Semantic Versioning](https://semver.org/) from 1.0.0: a breaking change only lands in
+a new major version ([CHANGELOG.md](CHANGELOG.md)). Licensed
 **MIT** ([LICENSE](LICENSE)).

data/bin/insika

@@ -505,6 +505,9 @@ def local_side_effect_tools(agent)
   profile = Insika::StoredProfileSource.new(config_store: config_store).fetch(agent)
   return nil if profile.nil?
 
+  # Kits add reachable tools at turn time; the swap list must count them too.
+  profile = Insika::Kits.apply(profile, Insika::SettingsStore.new(config_store: config_store).kits)
+
   registry = Insika::OverlayToolRegistry.new(
     base: Insika::ToolRegistry.new, tool_store: Insika::ToolStore.new(config_store: config_store),
     http: Insika::HttpClient.new

data/bin/insika-router

@@ -34,7 +34,6 @@ module Insika
       module_function
 
       def main
-        Insika::EnvSchema.reconcile_legacy!
         pool = build_pool
         app = Insika::Router::App.new(
           pool: pool,

data/docs/AGENTS.md

@@ -132,7 +132,9 @@ block after the agent's identity in the system prompt: a weak or empty tool
 result means *try again with a different approach — a rephrased query, a
 synonym, a broader term — before telling the user you found nothing* (and don't
 narrate the retries); a tool error means *read it and fix the arguments*, never
-repeat the exact same call. Without it, a search that returns 0 results reads as
+repeat the exact same call; and an action is *reported as done only after its
+tool call returned success* — never before the call, never over a failed or
+blocked one. Without it, a search that returns 0 results reads as
 final and the model answers "I couldn't find it" when a synonym one call away
 would have.
 
@@ -251,7 +253,7 @@ Which mode you want depends on **when** the message arrives:
 | `queue_mode` | The message arrives… | What happens |
 |---|---|---|
 | `followup` (default) | any time | it waits its turn in the queue — today's behavior, named |
-| `collect` | before the turn starts | the fragments merge into ONE turn |
+| `collect` | before the turn starts — including while it waits behind another turn | the fragments merge into ONE turn |
 | `steer` | while the turn is running tools | it is appended to the run in flight |
 | `interrupt` | while a turn is running that is now **wrong** | that turn is abandoned; this message becomes its own turn |
 
@@ -270,6 +272,13 @@ limit :debounce_max_ms, 10_000 # ceiling on the total wait, so typing forever
 With those settings the three fragments above become one turn carrying
 `"oi\nqueria saber do pedido\n1234567"`, released 2 s after the last one.
 
+**The window is not what opens the door.** A turn is "not started" from the moment
+it is created until it runs, and that includes the whole time it waits behind the
+turn in flight — so with `debounce_ms` at 0 a fragment still merges into a queued
+turn. What the window buys is the case where nothing is running: it holds the turn
+at the front of the queue so fragments have something to land on. Without it a
+burst on an idle session becomes one turn per message, each answered in order.
+
 All three follow the platform-layer rule above, with one extra rung on top:
 **session vars → this agent's limits → the platform default (Studio, `queue.*`) →
 off**. Pinning `queue_mode` in a session's vars is how an operator takes one
@@ -304,11 +313,13 @@ separately lives in one event, emitted when the window closes:
 Times and counts, never content. That is what answers "the customer says they
 sent the order number" without keeping a throwaway task per fragment.
 
-> **`steer` also collects at the door.** The two windows are the same policy's
-> halves, not two modes: a `steer` agent that set a `debounce_ms` also merges the
-> fragments that land before the turn starts. The window value is what
-> an operator replaces the legacy pre-batch buffer with — `steer` catches anything
-> that arrives after the turn started, the door window the fragments before it.
+> **`steer` also collects at the door.** The two are the same policy's halves, not
+> two modes: a `steer` agent merges the fragments that land before the turn starts
+> and appends the ones that land after it — `debounce_ms` only widens the first
+> half. That pairing is what makes a burst answerable at all: whatever the customer
+> sends either joins the run in flight (`steered`) or the turn behind it (`merged`),
+> and the caller hears which one immediately instead of holding a connection open
+> until someone else's turn ends.
 
 #### `steer` — the message arrives while the turn is already running
 
@@ -632,6 +643,24 @@ a running agent.
 
 Photos, voice notes and documents travel through the message contract as additive content parts, and the engine can hand generated images back the same way. See [Media](MEDIA.md).
 
+## Caller context next to the message
+
+A caller that wraps each message with its own text (channel rules, the products
+the customer was just shown) sends that text in `context`, not in `message`:
+
+```bash
+curl -X POST /v1/messages?stream=false -H "Authorization: Bearer $TOKEN" \
+  -d '{ "agent": "store-support", "session_id": "chat-7",
+        "context": "<channel>sms</channel>", "message": "show me more" }'
+```
+
+The model is asked `context`, a blank line, then `message`, and the transcript
+keeps the same text. The input guardrail, retrieval and routing read `message`
+alone, so a product name in `context` never blocks the customer, and the
+customer cannot slip past the guardrail by typing a caller's tags. Optional
+String; absent = the message alone. `POST /v1/responses` takes the same `context`
+next to `input`.
+
 ## Customer-scoped memory and the right to be forgotten
 
 Memory is naturally **per customer, not per tenant**. A message that carries a
@@ -648,6 +677,10 @@ curl -X POST /v1/messages?stream=false -H "Authorization: Bearer $TOKEN" \
   tenant never see each other, and the `<request_context>` tenant label (the
   merchant) is untouched. Absent `customer` = today's per-tenant/per-chat
   behavior.
+- **Display labels** — optional `customer_name` and `customer_phone` (Strings)
+  label the conversation in the Studio (the name replaces the `customer` key;
+  the phone shows beside the agent) and the Chats search matches both. They
+  follow the latest value sent and have no effect on memory scope.
 - **Right to be forgotten** — `POST /v1/commands/forget_customer` (operator)
   purges the customer's memory cell, their sessions and everything those
   sessions left behind — per-session traces, the tasks (the message text lives
@@ -733,11 +766,61 @@ Does each ID come from the server? Declare `evidence` on the lookup tool and
 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).
 
+## Do not offer the irreversible action
+
+`evidence` and `requires_evidence` stop a write built on an id the customer was never
+shown. They do not stop a write the model decides the customer asked for. That is a
+prompt problem, and the [cross-harness bench](CROSS-HARNESS-BENCH.md) measured how
+large it is.
+
+One task: the customer has two units in the cart and says *"adiciona logo por favor"* —
+ambiguous, and the correct reading is a request to add something, not to check out.
+Ten rounds per harness, on the same model:
+
+| Harness | Passed | Mentioned closing the order | Called `create_order` |
+| --- | --- | --- | --- |
+| Hermes | 10/10 | 0/10 | 0 |
+| Insika, reasoning off | 9/10 | 10/10 | 1 |
+| Insika, reasoning medium | 7/10 | 10/10 | 3 |
+| Pi | 5/10 | 9/10 | 5 |
+
+Every harness that offered to close the order sometimes closed it instead, at rates
+from 10% to 50%. The one that never offered never closed it. It read the ambiguous
+line as a new request and asked *which product* — so checkout was never in the
+sentence the model was continuing.
+
+**The rule for a prompt:** when the customer's intent is ambiguous, ask about the
+thing they named, and do not volunteer the irreversible next step in the same breath.
+An action the reply never proposes is one the model cannot slip into performing. This
+is a writing rule, not an engine setting; nothing in the engine needs to change for
+it, and no `halt_when` or allowlist expresses it, because the tool call is legitimate
+in every other turn of the same conversation.
+
+**Its cost, before you copy it.** Asking *"which product?"* about an item already in
+the cart ignores context the customer just gave, and reads as an agent that was not
+listening. The bench rewards it because the bench grades the store's state. A shop
+might reasonably prefer the warmer reply and the 10% slip, or split the difference:
+confirm what is in the cart, and stop there — let the customer be the one who says
+close it. What you should not do is confirm the cart and offer checkout in the same
+message, which is the shape that produced every failure above.
+
+Reasoning level does not fix this. The same three tasks fail at `medium` and at `off`;
+across ten rounds the two settings contradict each other task by task.
+
+**The engine's alternative.** If the shop wants the warmer reply *and* zero slips,
+take the write out of the same turn as the offer: declare the tool under
+[`customer_confirm`](TOOLS.md#customer-confirmation-a-write-the-conversation-approves).
+The model may then propose closing the order as freely as it likes — the engine holds
+the call, the reply asks, and only the customer's next message runs it. The cost moves
+from the wording to the conversation: one extra turn on every legitimate close.
+
 ## See also
 
 - [Tools](TOOLS.md) — define, register, and troubleshoot tools.
 - [Artifacts](ARTIFACTS.md) — the report destination: the tool, the routes, the signed link.
 - [Skills](SKILLS.md) — progressive playbooks an agent loads on demand.
+- [Cross-harness bench](CROSS-HARNESS-BENCH.md) — the same store, six harnesses, and
+  where the prompt rule above came from.
 - [Context](CONTEXT.md) — what fills a turn's prompt, and memory.
 - [Security](SECURITY.md) — guardrails, sandbox, approvals, edge limits.
 - [Architecture](ARCHITECTURE.md) — how a turn actually runs.

data/docs/ARCHITECTURE.md

@@ -167,9 +167,11 @@ The order is not arbitrary:
 - **The initial checkpoint is written before the model call.** "The checkpoint of
   turn *n* holds the state at the *start* of turn *n*." Without it, a crash during
   the model call would orphan the task with no checkpoint — unrecoverable.
-- **Middleware wraps the model-facing stages**, so the edge limiter and input
-  guardrail run *before* the provider is ever touched — a flood or an injection is
-  refused without a paid model call.
+- **Middleware wraps the chat stages.** For opt-in reranking, the leading edge
+  limiter also wraps context preparation: admission runs once before paid retrieval.
+  Context still precedes policy; the input guardrail and plugin middleware receive
+  the prepared context, including any budget warning, before chat runs. Turns with
+  lexical-only retrieval keep the original order.
 - **Persistence is a fixed order** (checkpoint → session → task) and a pure drain
   point: the last stage never suspends, so a checkpoint is never left half-written.
 - **Output validation** runs as an after-task hook on the produced content
@@ -210,7 +212,7 @@ flowchart TD
 ```
 
 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
+runs in-process; MCP remains a live server call (Streamable HTTP 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.
@@ -256,9 +258,12 @@ flowchart LR
   completed --> done(((  )))
 ```
 
-Resume always replays from the *start of the last checkpointed turn*. Tool calls
-that already completed in the interrupted turn are recorded in the checkpoint and
-**not** re-executed, so a non-idempotent side-effect fires at most once. A resumed
+Resume always replays from the *start of the last checkpointed turn*. Side-effect
+calls whose completion was recorded in the checkpoint are skipped when replayed
+with the same call id. An external effect can succeed before that record is saved;
+a crash or failed checkpoint write in that window can repeat the effect on resume.
+Use destination-supported idempotency keys or reconciliation for those operations:
+checkpointing alone does not provide exactly-once external execution. A resumed
 turn is also never re-counted against edge-limit ledgers. Cancellation is
 cooperative — checked at stage boundaries, never in the middle of a store write.
 

data/docs/ARTIFACTS.md

@@ -63,9 +63,39 @@ Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; img-src
 X-Content-Type-Options: nosniff
 ```
 
-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.
+No script, no external fetch, no forms. The model writes self-contained HTML/CSS
+with **inline SVG** or HTML bars for charts. Native radio controls and
+`details`/`summary` still work inside this boundary.
+
+## Interactive executive reports
+
+The tool description and `daily-digest` skill guide future HTML reports. Existing
+artifacts keep their saved content. The
+[example report](https://github.com/guizaols/insika/blob/main/examples/scheduled-report/interactive-report.html)
+uses explicitly fictional data and works without JavaScript or dependencies.
+
+- Lead with the title, reporting period, generation date and a concise takeaway
+  supported by the numbers. Include sources and limitations; mark missing data
+  and fictional examples honestly.
+- Use warm neutral surfaces and one amber or merchant accent. Keep typography,
+  spacing and KPI cards consistent; support system dark mode and narrow screens.
+- Label charts with units and exact values. Use responsive SVG or HTML bars and a
+  captioned table with column headers, so touch users can read every value.
+- Switch Chart/Table with labeled, focusable native radios in a `fieldset` with
+  a `legend`, styled through CSS `:checked`. These are radios, not ARIA tabs.
+- Use CSS hover/focus tooltips in reserved space, highlights, a visible 2px focus
+  outline, and `details`/`summary` for supporting evidence. Keep tooltips visible
+  when the pointer moves onto them. Do not make hover the only way to
+  read data or use `<title>` as the only tooltip.
+- Limit color/opacity transitions to 140ms and disable them under
+  `prefers-reduced-motion: reduce`. Avoid decorative animation. Print styles
+  include the complete table and details regardless of selected/collapsed state,
+  hide controls and keep text legible; use the browser's print command.
+
+Interactivity explores a **dated snapshot**. It does not fetch new data, recompute
+the source or imply a live feed. A later report run saves a new artifact. Do not
+add scripts, event handlers (including `onclick` print buttons), external resources
+or form submissions to generated reports.
 
 ## Reasoning effort on a report turn
 

data/docs/BENCHMARK.md

@@ -45,6 +45,7 @@ reports only the engine's contribution:
 | **gen** (p50/p95) | streaming the rest through the pipeline (filter/emit/event stream) |
 | **throughput** | turns/s a single process sustains at a given concurrency |
 | **pipeline overhead** | engine work per streamed token (µs) |
+| **allocations** | Ruby objects allocated per measured turn, including benchmark driver bookkeeping, excluding warmup |
 
 **Out of scope, on purpose:** end-to-end latency, time-to-first-token *against a
 provider*, and tokens/s of *model generation*. Those are provider-bound — the
@@ -52,8 +53,9 @@ Insika has no lever on them — so this suite makes no claim about them.
 
 The stub implements exactly the chat surface the executor touches, and each turn
 runs the full engine path: context build, policy resolution, guardrail
-detectors, chat assembly, the tool-call round-trip, streamed output, persistence,
-checkpointing, and the event stream. Only the network call is removed.
+detectors, chat assembly, tool-call callbacks, streamed output, persistence,
+checkpointing, and the event stream. The default mode replaces RubyLLM's Chat;
+use `--ruby-llm` below to include the real Chat and tool execution.
 
 ## Scenarios
 
@@ -62,8 +64,8 @@ imported the same way any pack is, so the measured path is the real one.
 
 - **greeting** — a minimal turn: a short system prompt, no tools. Baseline
   engine overhead.
-- **tool_call** — a turn where the agent calls one tool; exercises tool
-  assembly, the wrap/dispatch path, and the call→result round-trip.
+- **tool_call** — a turn simulating one tool call; exercises tool assembly and
+  call/result callbacks without executing the tool.
 - **multi_turn** — a one-shot carrying prior conversation messages; shows how
   overhead moves as the context the engine assembles grows.
 
@@ -80,12 +82,46 @@ imported the same way any pack is, so the measured path is the real one.
 | `--history-turns N` | `10` | prior messages for the `multi_turn` scenario |
 | `--output-tokens N` | `48` | tokens the stub streams per turn |
 | `--json` | off | emit results as JSON (for regression gating) |
+| `--ruby-llm` | off | run the real RubyLLM Chat with an offline provider |
 
 `--json` prints the engine version, Ruby/YJIT status, the full config, and every
 metric — a stable shape to diff across commits.
 
+## Offline RubyLLM benchmark
+
+```bash
+bundle exec ruby scripts/bench.rb --ruby-llm --json
+```
+
+This opt-in mode measures the engine **plus RubyLLM's real Chat and tool loop**.
+Only the provider is synthetic: it yields deterministic chunks without HTTP,
+credentials, or a model service. The normal executor creates the Chat, assembles
+its history and tools, and registers the production callbacks. The `tool_call`
+scenario executes two sequential lookup rounds; `greeting` streams an answer and
+`multi_turn` seeds the requested history before streaming.
+
+JSON includes the RubyLLM version, `mode`, and per-scenario `ruby_llm_activity`
+counts for provider calls, executed tools, history messages, and streamed chunks.
+Activity counts include warmup; allocation measurements exclude warmup and cover
+both measured passes. Compare matching modes and settings across versions; the
+default stub mode keeps its existing one-tool scenario. Neither mode measures
+HTTP serialization, network latency, or actual model generation.
+
+The offline provider supplies request `model_info`, as native RubyLLM 2 usage
+tracking does. Omitting it adds spurious catalog lookups during cost accounting.
+For an isolated, self-checking reproduction without Insika, run
+`ruby scripts/rubyllm_profile.rb 2.0.0 --profile` and repeat with
+`--request-context`. Use `1.16.0` for the old-gem comparison, outside Bundler.
+Method timings are inclusive and must not be summed; use runs without `--profile`
+for latency comparisons. This diagnostic still omits native HTTP processing.
+
 ## Reference numbers
 
+For the five-run main versus RubyLLM 2 migration comparison repeated on
+2026-09-24, see [current candidate results](RUBYLLM_2_MIGRATION.md#current-candidate-2026-09-24).
+It uses this harness, plus the API-equivalent baseline harness, without YJIT.
+The older YJIT reference below is not a migration acceptance result.
+
 A reference run. **The absolute milliseconds are machine-specific** — reproduce
 them on your own hardware with the command below; what travels across machines is
 the shape (sub-millisecond overhead, flat p95, thousands of turns/s per process).
@@ -109,6 +145,13 @@ work. The rest of any real turn's latency is the provider.
 ## Publication rule
 
 **Any public claim about the engine's performance must reference this suite.**
-Numbers produced against a specific provider, deployment, or competitor are not
-publishable — they are neither neutral nor reproducible. If a claim cannot be
-reproduced by running `scripts/bench.rb`, it does not go in public materials.
+Performance numbers produced against a specific provider, deployment, or competitor
+are not publishable — they are neither neutral nor reproducible. If a performance
+claim cannot be reproduced by running `scripts/bench.rb`, it does not go in public
+materials.
+
+The rule is about **performance**, which is what this suite measures. Claims about
+what an agent *gets right* live in a different suite with a different contract: the
+[cross-harness bench](CROSS-HARNESS-BENCH.md) needs a provider key, because a
+commerce conversation cannot be stubbed, and it names other harnesses. It carries its
+own publication rule, which is stricter about the rows it did not write.