insika 0.7.0 → 0.8.0

data/docs/OBSERVABILITY.md

@@ -25,7 +25,9 @@ authoring writes (`:golden_written`, `:agent_file_written`, …), queue bookkeep
 channel delivery (`:channel_delivered` — see [Channels](CHANNELS.md))
 travel the same stream and are **ignored** by the bridge: they open no span and
 touch no instrument, because they are not part of a turn's latency or cost. Any
-other subscriber still sees them.
+other subscriber still sees them. The one mid-turn event the bridge does consume
+is `:tool_loop_intervened` — it feeds the `insika.tool.loop_intervened` counter
+(no span: the intervention is a fact about the turn, not a timed operation).
 
 They are worth subscribing to even so, because each is the ONLY record of
 something that left no task of its own behind:
@@ -145,12 +147,32 @@ knows its outcome.
 | `insika.cost` | counter | `{USD}` | the turn's model is priced (see below) |
 | `insika.tool.calls` | counter | `{call}` | a tool call completes |
 | `insika.tool.duration` | histogram | `s` | a `tool_call`/`tool_result` pair completes |
+| `insika.cache.hit_rate` | histogram | `%` | a turn reported billed prompt tokens (see below) |
+| `insika.tool.loop_intervened` | counter | `{intervention}` | the loop detector delivered its one-shot warning |
+| `insika.context.compacted` | counter | `{compaction}` | an in-session compaction was persisted (RFC-0044) |
 
 `insika.tool.duration` is deliberately **not** recorded for data-tools: those are a
 single point-in-time event, so there is no measured duration to report. A tool left
 open by a mid-turn failure is not counted as a completed call either — its span is
 closed, but a failed call must not inflate the success histogram.
 
+`insika.cache.hit_rate` is the same arithmetic the Studio's per-agent series uses:
+cache **reads** over the whole **billed** prompt (fresh input + cache reads + cache
+writes), always in `[0,100]`. A turn with no billed prompt tokens records nothing —
+absence is not a 0% hit. It is recorded per turn on the terminal event, so it
+carries the turn labels (`insika.agent`, `insika.model`, …); the token-counter
+recipe below still works and answers the fleet-wide version of the question.
+
+`insika.tool.loop_intervened` counts deliveries of the loop detector's one
+warning per turn (see [Agents](AGENTS.md) `max_tool_repeat`), labelled with
+`insika.tool`. It counts interventions, not repeats: a turn contributes at most 1.
+
+`insika.context.compacted` counts persisted in-session compactions
+(`:context_compacted` — see [Context](CONTEXT.md)), labelled with
+`insika.agent` and `insika.model` (the summarizer's model, not the turn's). It
+fires post-turn, after the turn span already closed, so it deliberately rides
+its own labels rather than the open-turn set.
+
 ## Attribute reference
 
 The same names are used on spans and on metrics. **Metrics carry a deliberate
@@ -267,7 +289,14 @@ climbing while `input` stays flat.
 
 **Cache hit ratio**
 `insika.tokens` filtered to `insika.token.type="cached"` over the same counter
-filtered to `input`. This is the number that moves your bill.
+filtered to `input`. This is the number that moves your bill. For the per-turn
+distribution (does every turn hit, or do fleet averages hide cold agents?), chart
+`insika.cache.hit_rate` — p50 by `insika.agent`; a healthy agent sits near 100.
+
+**Loop interventions**
+`insika.tool.loop_intervened`, rate, grouped by `insika.agent` and `insika.tool`.
+Any sustained non-zero rate means one tool keeps being retried with identical
+arguments — fix the tool's contract or the prompt, not the detector.
 
 **Spend per tenant**
 `insika.cost`, rate (or `increase` over a billing window), grouped by

data/docs/POLICY.md

@@ -18,13 +18,19 @@ matters, and editable hot.
 ## Layer 1: Tools (what it can call)
 
 `tools_allow` / `tools_deny` / `tools_allow_groups` decide which tools enter the
-turn's tool-loop, enforced by the tool-allowlist policy. See [Tools](TOOLS.md)
-for how tools are defined and registered, and [`examples/data-tool/`](https://github.com/guizaols/insika/tree/main/examples/data-tool/).
+turn's tool-loop, enforced by the builtin `tool_allowlist` policy — which the
+engine adds for you the moment any of the three is declared, so you never have to
+name it in `policies` (see [Agents](AGENTS.md#the-allowlist-convention)). See
+[Tools](TOOLS.md) for how tools are defined and registered, and
+[`examples/data-tool/`](https://github.com/guizaols/insika/tree/main/examples/data-tool/).
 
 ## Layer 2: Policies and approvals
 
-Policies are named entries evaluated before the turn runs. Builtins cover
-tool-, skill-, and workflow-allowlisting, plus **`ApprovalRequired`** — which
+Policies are named entries evaluated before the turn runs. **Only the policies a
+profile names run** — which is why `tool_allowlist` is added implicitly by a
+declared tool list; an allowlist nobody applies is worse than no allowlist.
+Builtins cover tool-, skill-, and workflow-allowlisting, plus
+**`ApprovalRequired`** — which
 does not allow or deny but *tags* a tool as needing human approval. Set
 `approvals_required: [tool names]`; the gate then fires when the model tries to
 call that tool, suspending the turn until an operator approves it in the Studio.

data/docs/RUNNING-LOCAL.md

@@ -62,7 +62,7 @@ whole surface answers `503`, never open by omission.
 | `INSIKA_DB` | — (ephemeral memory) | SQLite path → config + execution survive a restart |
 | `BIND` | `http://localhost:9292` | host:port |
 | `ADMIN_TOKEN` | `local-demo` | token for `/studio` |
-| `OPENCLAW_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for the whole `/v1` + `/a2a` surface |
+| `INSIKA_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for the whole `/v1` + `/a2a` surface |
 | `DEEPSEEK_MODEL` | `deepseek-v4-flash` | model |
 
 With persistence:
@@ -128,7 +128,7 @@ Provision it (runs as a client against the live server; the internal token comes
 from the environment, never disk):
 
 ```bash
-INSIKA_URL=http://localhost:9292 OPENCLAW_GATEWAY_TOKEN=local-demo \
+INSIKA_URL=http://localhost:9292 INSIKA_GATEWAY_TOKEN=local-demo \
   bundle exec ruby scripts/import_pack.rb /path/to/pack
 ```
 

data/docs/SECURITY.md

@@ -27,7 +27,7 @@ The layers, from the edge inward:
 ## The Bearer gate
 
 The `/v1` and `/a2a` surface answers only with
-`Authorization: Bearer <OPENCLAW_GATEWAY_TOKEN>` (which falls back to `ADMIN_TOKEN`).
+`Authorization: Bearer <INSIKA_GATEWAY_TOKEN>` (which falls back to `ADMIN_TOKEN`).
 The check runs in the router, **before** any dispatch, against an **allowlist** of
 public routes — so a route added later is closed until someone deliberately publishes
 it. Only these answer without a token:

data/docs/SOAK.md

@@ -88,7 +88,7 @@ insika soak --dry-run --envelope soak-envelope.md
 # every precondition, and nothing else
 insika soak --preflight --envelope soak-envelope.md
 
-# the run itself (INSIKA_URL + OPENCLAW_GATEWAY_TOKEN, like loadtest.rb)
+# the run itself (INSIKA_URL + INSIKA_GATEWAY_TOKEN, like loadtest.rb)
 INSIKA_URL=https://<target> insika soak --run --envelope soak-envelope.md --out soak-out/
 
 # resume after a short outage (the gap is recorded and counts against the window)

data/docs/TOOLS.md

@@ -485,6 +485,30 @@ and gets the URL back; the tenant is bound from the turn, never a parameter the
 model types. See [Artifacts](ARTIFACTS.md) for the tool contract, the serving
 routes, the signed link and the retention/LGPD reach.
 
+## The usage report — `insika tools:report`
+
+The per-session trace answers "what did this conversation call"; nothing used to
+answer "what does this agent carry and never use". The report aggregates the
+stored traces per agent (tasks → sessions → `tool_traces`, the same read the
+Studio does) and flags three shapes:
+
+- **`never_called`** — in `tools_allow`, zero calls in any stored trace. Dead
+  weight: its schema ships on every request and buys nothing.
+- **`error_rate`** — over 30% conventional errors (the trace's `ok` flag) inside
+  the window (default 14 days). Either the tool is broken or the model cannot
+  hold its contract.
+- **`stale`** — called at some point, but not once inside the window.
+
+```bash
+insika tools:report                        # every stored agent
+insika tools:report --agent store-support  # one agent
+insika tools:report --days 30 --json       # wider window, machine-readable
+```
+
+Read-only by design: the report names candidates, the **operator** removes — a
+flagged tool may still be the one a rare but critical flow needs. Counts are
+"at least", never exact: the trace keeps a capped tail per session.
+
 ## See also
 
 - [Agents](AGENTS.md) — allowlists, groups, and per-agent tool exposure.

data/docs/prompts/GO-LIVE.md

@@ -40,7 +40,7 @@ convenience only:
 | Token | Gates | Rotating it |
 |---|---|---|
 | `ADMIN_TOKEN` | `/studio` login (the operator — just you) | safe, independent |
-| `OPENCLAW_GATEWAY_TOKEN` | Bearer for `/v1/responses` + `/v1/agents` (your API consumers) | both sides together, same step |
+| `INSIKA_GATEWAY_TOKEN` | Bearer for `/v1/responses` + `/v1/agents` (your API consumers) | both sides together, same step |
 
 Generate each: `ruby -rsecurerandom -e 'puts SecureRandom.hex(24)'`. Set them as
 platform env vars. **Never** write either into a file, a commit, or your own output.
@@ -77,7 +77,7 @@ Any Docker host, same contract:
 ```bash
 docker build -t insika .
 docker run -p 9292:9292 -v insika-data:/data \
-  -e DEEPSEEK_API_KEY=... -e ADMIN_TOKEN=... -e OPENCLAW_GATEWAY_TOKEN=... \
+  -e DEEPSEEK_API_KEY=... -e ADMIN_TOKEN=... -e INSIKA_GATEWAY_TOKEN=... \
   insika
 ```
 
@@ -92,7 +92,7 @@ In order, each with evidence:
 
 ```bash
 curl -N https://<host>/v1/responses \
-  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
+  -H "Authorization: Bearer $INSIKA_GATEWAY_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"model":"<agent-id>","user":"go-live-check","input":"hello"}'
 ```

data/lib/insika/agent_profile.rb

@@ -333,7 +333,9 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
         tools_deny: Array(tools_deny), tools_allow_groups: tools_allow_groups, skills: skills,
         skills_eager: skills_eager,
         context_providers: context_providers, workflows_allow: workflows_allow,
-        policies: Array(policies), prompt_refs: Array(prompt_refs),
+        policies: normalize_policies(policies, tools_allow: tools_allow, tools_deny: tools_deny,
+                                     tools_allow_groups: tools_allow_groups),
+        prompt_refs: Array(prompt_refs),
         limits: DEFAULT_LIMITS.merge(limits), approvals_required: approvals_required,
         capabilities: capabilities,
         # opt-in like capabilities: nil => NONE. Array-normalize a present value so
@@ -400,6 +402,29 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
       )
     end
 
+    # Declaring a tool allow/deny list IS opting into it. The list is only ever
+    # applied by the builtin `tool_allowlist` policy, and the Policy::Engine runs
+    # ONLY the policies a profile names — so a profile with `tools_allow: [a, b]`
+    # and no policies sent EVERY registered tool to the model, silently. A
+    # declared allowlist that does nothing is the failure mode; same rule as the
+    # "mcp:<name>" group auto-added to `tools_allow_groups` by the DSL.
+    #
+    # Presence, not emptiness, is the trigger for the two nil-able lists:
+    # `tools_allow: []` means "no tools" and must enforce just as hard.
+    # `tools_deny` has no nil state (it defaults to []), so only a non-empty
+    # deny list counts as a declaration.
+    #
+    # Appended, never prepended: profile-declared policies keep their order. The
+    # engine intersects allows and unions denies, so position changes only the
+    # audit order, not the outcome.
+    def self.normalize_policies(policies, tools_allow:, tools_deny:, tools_allow_groups:)
+      names = Array(policies)
+      declared = !tools_allow.nil? || !tools_allow_groups.nil? || !Array(tools_deny).empty?
+      return names unless declared && names.none? { |n| n.to_s == "tool_allowlist" }
+
+      names + ["tool_allowlist"]
+    end
+
     # nil/absent -> nil; a single Hash -> [Hash]; else an Array of Hashes —
     # deep-stringified so JSON round-trips stay stable.
     def self.normalize_schedules(list)

data/lib/insika/chat_builder.rb

@@ -332,20 +332,29 @@ module Insika
     end
 
     # RubyLLM's additive callbacks become events. load_skill becomes
-    # :skill_activated. Adds the max_tool_calls counter: the loop is RubyLLM's;
-    # here we only count and abort.
+    # :skill_activated. Hangs the turn's TurnBudget on them: the loop is
+    # RubyLLM's; here we only count, warn and abort.
     def wire_callbacks(chat, state, emit)
-      # Per-TURN counter: safe as a closure local even under concurrent tool calls
-      # (MRI fibers do not preempt between the read and the write). The per-CALL
-      # correlation is NOT — it lives in fiber storage behind TurnState, because
-      # each call gets its own fiber once tool concurrency is on.
-      tool_calls = 0
-      max_tool_calls = state.profile.limits[:max_tool_calls] || 50
+      # The turn's ONE tool-call counter. Safe as a closure-held object even
+      # under concurrent tool calls (MRI fibers do not preempt between the read
+      # and the write). The per-CALL correlation is NOT — it lives in fiber
+      # storage behind TurnState, because each call gets its own fiber once tool
+      # concurrency is on.
+      #
+      # It counts, warns at 10/5/2 calls remaining, and raises the
+      # `stage: :tool_limit` abort — the guard-rail that used to be inline here.
+      # Announcing the budget needs #add_message at the batch boundary; a chat
+      # without it (smoke shim, minimal double) still gets the count and the
+      # abort, just no notice.
+      budget = Insika::TurnBudget.new(
+        chat: chat, max: state.profile.limits[:max_tool_calls] || 50, emit: emit
+      )
 
       # the loop detector. Needs #after_message + #add_message for the
       # batch-boundary intervention; a chat without them (smoke shim, minimal
       # double) stays bounded by max_tool_calls alone — never half-wired.
-      detector = if %i[after_message add_message].all? { |m| chat.respond_to?(m) }
+      appendable = %i[after_message add_message].all? { |m| chat.respond_to?(m) }
+      detector = if appendable
                    repeat = state.profile.limits[:max_tool_repeat] || Insika::AgentProfile::DEFAULT_LIMITS[:max_tool_repeat]
                    Insika::LoopDetector.new(chat: chat, limit: repeat, emit: emit) if repeat >= 2
                  end
@@ -355,11 +364,7 @@ module Insika
         state.current_tool_call = tool_call
         # max_tool_calls guard-rail: stays inline (not as a registered hook)
         # because Hooks is shared across turns and has no unregister.
-        tool_calls += 1
-        if tool_calls > max_tool_calls
-          raise Insika::TimeoutError.new("tool call limit exceeded (#{max_tool_calls})",
-                                           stage: :tool_limit)
-        end
+        budget.tool_call
 
         # AFTER the count, BEFORE the call runs — a post-warning
         # repeat raises here, so the stubborn loop pays for no extra call.
@@ -394,13 +399,19 @@ module Insika
         # the RAW result — the only place a Tool::Halt (halt_when) is
         # still recognizable, and a halted batch must receive no intervention.
         detector&.tool_result(result)
+        budget.tool_result(result)
         result = @hooks.run_after(:tool, result)
         emit.call(:tool_result, { name: state.current_tool_name, result: result.to_s })
       end
 
-      # the intervention appends at the batch boundary (the Nth tool
-      # result closing) — never between two tool results of one batch.
-      chat.after_message { |message| detector.message_ended(message) } if detector
+      # both appends land at the batch boundary (the Nth tool result closing) —
+      # never between two tool results of one batch.
+      return unless appendable
+
+      chat.after_message do |message|
+        detector&.message_ended(message)
+        budget.message_ended(message)
+      end
     end
   end
 end

data/lib/insika/compaction.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Insika
+  # In-session compaction: when a session's UNCOMPACTED transcript
+  # grows past `compact_after` messages, everything but the last `keep_last`
+  # is summarized by a cheap model into one fragment; the tail stays verbatim.
+  # This module is the pure half — boundary math, the prompt, and the
+  # Summarizer over an injected ask (the Distiller shape: unit-testable
+  # without a provider). The trigger lives in the Executor (post-turn, off
+  # the critical path); the persistence in SessionStore#set_compaction; the
+  # read path in Context::Providers::Session.
+  module Compaction
+    DEFAULT_KEEP_LAST = 20
+    DEFAULT_COMPACT_AFTER = 40
+    # A summary that outgrows this is truncated — the compaction must never
+    # grow the context it exists to shrink.
+    MAX_SUMMARY_CHARS = 6_000
+    # Per-message cap in the transcript slice sent to the summarizer (a
+    # `role: tool` body can be 4 000 chars in the store); the head of a long
+    # result carries the identity of what happened, which is what a summary needs.
+    MESSAGE_CHAR_CAP = 1_000
+
+    # The engine's generic prompt. A platform `compaction.prompt` REPLACES it
+    # wholesale (the distill convention) — the engine never writes store
+    # vocabulary. The preserve-list is the P28 contract: facts (CEP, order
+    # numbers), commitments, the MISSING list, decisions.
+    DEFAULT_PROMPT = <<~PROMPT.freeze
+      You are compacting the OLD part of an ongoing customer conversation into
+      one summary that the assistant will read INSTEAD of those messages. The
+      recent messages stay verbatim; your summary is the only surviving trace
+      of the old ones — anything you drop is gone for good.
+
+      Preserve, verbatim where short:
+      - every fact the customer stated (sizes, budget, address, postal code/CEP,
+        order numbers, product choices, dates, quantities);
+      - every commitment the assistant made (promises, prices quoted, delivery
+        windows, agreed next steps);
+      - what was asked and is still unanswered (the missing information);
+      - decisions already made, so nothing gets re-asked or re-litigated.
+
+      Do not invent, do not editorialize, do not add advice. Answer with the
+      summary text only — plain text, compact, in the conversation's own language.
+    PROMPT
+
+    # The compaction plan: summarize messages[from...upto] (from = the previous
+    # boundary), keep messages[upto..] verbatim. count = upto - from.
+    Plan = Data.define(:from, :upto, :count)
+
+    module_function
+
+    # Decides whether (and what) to compact. -> Plan | nil.
+    #   messages: the session transcript (append-only, RFC-0016).
+    #   state:    the persisted "compaction" hash ({"upto"=>, ...}) | nil.
+    #   config:   the Settings "compaction" hash (keep_last/compact_after).
+    # `compact_after` is clamped to at least `keep_last` so the plan always
+    # moves the boundary forward. The boundary retreats over `role: "tool"`
+    # messages so an eviction unit (assistant-with-tool_calls + its results)
+    # is never split — the whole cycle stays verbatim instead.
+    def plan(messages:, state:, config:)
+      msgs = Array(messages)
+      keep_last = positive(config && config["keep_last"], DEFAULT_KEEP_LAST)
+      compact_after = positive(config && config["compact_after"], DEFAULT_COMPACT_AFTER)
+      compact_after = keep_last if compact_after < keep_last
+      from = state ? state["upto"].to_i : 0
+      return nil unless msgs.size - from > compact_after
+
+      upto = msgs.size - keep_last
+      upto -= 1 while upto > from && role_of(msgs[upto]) == "tool"
+      return nil unless upto > from
+
+      Plan.new(from: from, upto: upto, count: upto - from)
+    end
+
+    # The full prompt for one compaction run: the base rules, the PREVIOUS
+    # summary (so a fact from turn 3 survives every re-compaction — each
+    # summary folds the last one in) and only the NEW slice. The slice is
+    # sent UNREDACTED on purpose: it replaces transcript the main model
+    # already reads raw, inside the same trust boundary, and redaction would
+    # delete exactly the facts (CEP, order id) the summary must preserve.
+    def prompt(messages:, plan:, previous: nil, base: nil)
+      rules = Coercion.presence(base.to_s) || DEFAULT_PROMPT
+      parts = [rules.rstrip]
+      if Coercion.presence(previous.to_s)
+        parts << "## The summary so far (fold it into the new one — its facts must survive)\n\n#{previous}"
+      end
+      parts << "## The messages to compact\n\n#{transcript(messages, plan)}"
+      parts.join("\n\n")
+    end
+
+    # "[i] role: content" over the plan's slice, one line per message; a
+    # tool-calling assistant message with no text renders the tool names.
+    def transcript(messages, plan)
+      Array(messages)[plan.from...plan.upto].to_a.each_with_index.map do |msg, offset|
+        "[#{plan.from + offset}] #{role_of(msg)}: #{text_of(msg)}"
+      end.join("\n")
+    end
+
+    def role_of(msg) = (msg["role"] || msg[:role]).to_s
+
+    def text_of(msg)
+      content = (msg["content"] || msg[:content]).to_s.strip.gsub(/\s+/, " ")
+      if content.empty?
+        calls = msg["tool_calls"] || msg[:tool_calls]
+        names = Array(calls).filter_map { |c| c.is_a?(Hash) ? (c["name"] || c[:name] || c.dig("function", "name")) : nil }
+        content = names.empty? ? "(empty)" : "(tool calls: #{names.join(', ')})"
+      end
+      content[0, MESSAGE_CHAR_CAP]
+    end
+
+    def positive(value, default)
+      n = value.to_i
+      n.positive? ? n : default
+    end
+
+    # The one place compaction asks a model for anything. Pure over an
+    # injected `ask` (the Distiller shape); the real ask is a lambda built by
+    # SummarizerFactory (ruby_llm required lazily, load_guard stays green).
+    class Summarizer
+      # A blank answer must not overwrite the boundary — empty output is a
+      # loud failure, never "the old turns said nothing".
+      class Unusable < Insika::ValidationError; end
+
+      # ask:   ->(prompt) { "<raw model text>" } | something answering #content
+      #        (+ #input_tokens/#output_tokens/#cached_tokens for cost).
+      # model: the ref recorded on the event ("utility_model" default).
+      attr_reader :model
+
+      def initialize(ask:, model: "utility_model")
+        @ask = ask
+        @model = model.to_s
+      end
+
+      # -> { summary: String, cost: { "spent" => N, "cached" => N } | nil }
+      # Raises Unusable on a blank answer; truncates past MAX_SUMMARY_CHARS.
+      def summarize(prompt:)
+        answer = @ask.call(prompt)
+        text = Coercion.utf8(text_of(answer)).strip
+        raise Unusable, "the summarizer answered with nothing" if text.empty?
+
+        { summary: text[0, MAX_SUMMARY_CHARS], cost: cost_of(answer) }
+      end
+
+      private
+
+      def text_of(answer) = (answer.respond_to?(:content) ? answer.content : answer).to_s
+
+      # nil when the provider said nothing — never 0 (the Distiller's
+      # discipline). The cached prefix is INCLUDED in the spent total.
+      def cost_of(answer)
+        return nil unless answer.respond_to?(:input_tokens) && answer.respond_to?(:output_tokens)
+
+        input = answer.input_tokens.to_i
+        output = answer.output_tokens.to_i
+        cached = answer.respond_to?(:cached_tokens) ? answer.cached_tokens.to_i : 0
+        { "spent" => input + output, "cached" => cached }
+      end
+    end
+
+    # Resolves WHICH model summarizes and builds the ask. compaction.model ->
+    # platform utility_model -> nil (nil means "feature inert", never a guess —
+    # the DistillerFactory ladder). NOT the fallbacks chain: that one answers
+    # "which model serves the customer turn". `ask_factory`/`llm` injectable (specs).
+    module SummarizerFactory
+      module_function
+
+      # config: the Settings "compaction" hash. -> Summarizer | nil
+      def build(config, utility_model: nil, ask_factory: nil, llm: nil)
+        ref = Coercion.presence(config && config["model"]) || Coercion.presence(utility_model)
+        return nil if ref.nil?
+
+        provider, model = split_ref(ref)
+        factory = ask_factory || ->(m, p) { ruby_llm_ask(m, p, llm: llm) }
+        Summarizer.new(ask: factory.call(model, provider), model: ref)
+      end
+
+      # "provider/model" -> [provider, model]; "model" -> [nil, model] — one
+      # syntax for "which model" across features (DistillerFactory's reading).
+      def split_ref(ref)
+        prov, name = ref.to_s.split("/", 2)
+        name ? [prov, name] : [nil, prov]
+      end
+
+      # Temperature 0: the same slice must compact to the same boundary
+      # deterministically. `ruby_llm` is required lazily so nothing loads a
+      # provider gem until compaction is actually configured (load_guard stays green).
+      def ruby_llm_ask(model, provider, llm: nil)
+        require "ruby_llm"
+        llm ||= RubyLLM
+        lambda do |prompt|
+          llm.chat(model: model, provider: provider, assume_model_exists: true)
+             .with_temperature(0).ask(prompt)
+        end
+      end
+    end
+  end
+end

data/lib/insika/context/builder.rb

@@ -151,13 +151,17 @@ module Insika
       identity, volatile = system_frags.partition { |f| (f.layer || :volatile) == :identity }
       system_frags = sort_canonical(identity) + sort_canonical(volatile)
       history_frags = fragments.select { |f| f.placement == :history } # production order (chronological)
+      # :tail renders after ALL history — the last thing before the current user
+      # message. Attention is strongest at the end of the context, so the goal
+      # restated here survives a 30-call turn that the head prompt no longer does.
+      tail_frags = fragments.select { |f| f.placement == :tail }
       tool_frags = fragments.select { |f| f.placement == :tool_context }
 
       system = system_frags.map(&:content).join("\n\n")
-      history = history_frags.map(&:content)
+      history = history_frags.map(&:content) + tail_frags.map(&:content)
       tool_context = tool_frags.empty? ? nil : tool_frags.map(&:content).join("\n\n")
 
-      canonical = system_frags + history_frags + tool_frags
+      canonical = system_frags + history_frags + tail_frags + tool_frags
       ContextPackage.new(
         system: system, history: history, tool_context: tool_context,
         fragments: canonical, budget: { cap: cap, used: canonical.sum(&:tokens), evicted: evicted }

data/lib/insika/context/fragment.rb

@@ -3,7 +3,10 @@
 module Insika
   # Unit of context produced by a provider.
   # SHARED type (Insika::, not Insika::Context::).
-  #   placement: :system | :history | :tool_context
+  #   placement: :system | :history | :tail | :tool_context
+  #              :tail renders AFTER the whole history, i.e. as the last thing
+  #              the model reads before the current user message. Its content is
+  #              a message Hash ({role:, content:}), like a :history fragment.
   #   priority:  Integer; higher = more important (survives cuts)
   #   tokens:    Integer | nil; estimated by the Builder when nil
   #   source:    String — provider id (audit)

data/lib/insika/context/priority.rb

@@ -17,6 +17,9 @@ module Insika
     # the injected block.
     module Priority
       IDENTITY     = 100 # IDENTITY/SOUL (Prompt) — pinned
+      RECITATION   = 95  # <recitation> the goal restated at the TAIL of context
+                         #   (Briefing). Never cut: it is two lines, and the one
+                         #   turn it gets evicted is the long turn that needed it.
       PROMPT_REF   = 90  # Prompt Catalog guardrails/refs (Prompt) — pinned
       SKILL_BODY   = 85  # <active_skill> trigger-matched body (SkillTrigger)
       SKILL        = 80  # <available_skills> level 1 (Skill)
@@ -29,6 +32,9 @@ module Insika
                          #   pinned prefix), above the turn's own <request_context>.
       HISTORY_MAX  = 79  # history ceiling by recency (Session)
       HISTORY_BASE = 60  # history base; +idx up to the ceiling (Session)
+      COMPACTION   = 59  # <conversation_summary> the compacted prefix (RFC-0044)
+                         #   — one step below the oldest verbatim message: under
+                         #   budget it is the "oldest unit" and drops first.
       REQUEST      = 40  # <request_context> — turn injection, the most cuttable
     end
   end