insika 0.1.0 → 0.3.0

data/lib/insika/channels/relay.rb

@@ -3,12 +3,13 @@
 require "digest"
 require "json"
 require "openssl"
+require "time"
 require "uri"
 
 module Insika
   module Channels
     # The channel for an adopter who ALREADY owns a messaging integration
-    # (RFC-0011 §6). A WhatsApp BSP, a Zendesk, a legacy Rails app: they want the
+    # A WhatsApp BSP, a Zendesk, a legacy Rails app: they want the
     # engine for the TURN, not for the platform. Two routes and an envelope —
     #
     #   consumer --POST /channels/relay/events--> engine   acked now, never the reply
@@ -16,7 +17,7 @@ module Insika
     #
     # — and everything platform-shaped stays theirs: the 24-hour window, template
     # approval, media, read receipts, and how markdown becomes WhatsApp formatting
-    # (§6.3). That is the promise, not the limitation: an integration someone has
+    # That is the promise, not the limitation: an integration someone has
     # already tuned for years does not have to move for them to adopt the engine.
     # A relay that starts growing template logic has stopped being a relay.
     #
@@ -33,12 +34,25 @@ module Insika
       DEFAULT_ID = "relay"
       DEFAULT_TIMEOUT = 10
 
+      # how the outbox flushes for THIS channel. `:at_end` (the
+      # default) is one POST with the whole answer, byte-identical to today;
+      # `:progressive` lets ChannelDelivery split the answer into balloons and
+      # POST them in order (the channel still only translates — it does not know
+      # what a balloon is).
+      POLICIES = %i[at_end progressive].freeze
+
       attr_reader :id
 
       # The bundled relay as an operator configures it: three env vars, of which the
       # token is the SWITCH — no token, no channel, so there is no way to end up with
       # this route mounted and open. -> Relay | nil.
       #
+      # `INSIKA_RELAY_SHADOW` (truthy) is the shadow switch: the turn
+      # runs end to end and the reply is recorded, never delivered.
+      #
+      # `INSIKA_RELAY_DELIVERY` ("progressive" | "at_end") is how the outbox
+      # flushes. Unset = :at_end.
+      #
       # Shared by every composition root on purpose: the DSL front door has to reach
       # the same feature as `config.ru`, or the docs are true of only one of them.
       def self.from_env(env = ENV, http: nil, allow_http: false, allow_private: false)
@@ -48,6 +62,8 @@ module Insika
         new(inbound_token: token,
             deliver_url: Insika::EnvSchema.read("INSIKA_RELAY_DELIVER_URL", env),
             deliver_token: Insika::EnvSchema.read("INSIKA_RELAY_DELIVER_TOKEN", env),
+            shadow: Insika::EnvSchema.truthy?(Insika::EnvSchema.read("INSIKA_RELAY_SHADOW", env)),
+            delivery: policy!(Insika::EnvSchema.read("INSIKA_RELAY_DELIVERY", env)),
             http: http, allow_http: allow_http, allow_private: allow_private)
       end
 
@@ -59,9 +75,14 @@ module Insika
       #                 reply and the delivery fails loudly instead of silently).
       # deliver_token:  Bearer we send THEM. Optional: a consumer on a private
       #                 network may authenticate us another way.
+      # shadow: The turn runs, the reply is recorded and never
+      #                 sent. Fail-closed by construction: everything downstream
+      #                 duck-types `shadow?`, so a channel that does not answer it
+      #                 is a normal channel.
+      # delivery: How the outbox flushes (:at_end | :progressive).
       def initialize(inbound_token:, deliver_url:, deliver_token: nil, http: nil,
                      id: DEFAULT_ID, allow_http: false, allow_private: false,
-                     timeout: DEFAULT_TIMEOUT)
+                     timeout: DEFAULT_TIMEOUT, shadow: false, delivery: :at_end)
         @id = id.to_s
         @inbound_token = inbound_token.to_s
         @deliver_url = deliver_url.to_s
@@ -70,10 +91,30 @@ module Insika
         @allow_http = allow_http
         @allow_private = allow_private
         @timeout = timeout
+        @shadow = shadow
+        @delivery = self.class.policy!(delivery)
+      end
+
+      def shadow? = @shadow
+
+      def delivery = @delivery
+      def progressive? = @delivery == :progressive
+
+      # "progressive" | "at_end" | blank/unset (= :at_end). An unknown value is
+      # a config error at BOOT — the consumer would silently miss every
+      # progressive turn, so it is refused where the operator is.
+      def self.policy!(value)
+        return :at_end if Insika::Coercion.blank?(value)
+
+        name = value.to_s.strip.downcase.to_sym
+        return name if POLICIES.include?(name)
+
+        raise Insika::ConfigError,
+              "unknown relay delivery: #{value.inspect} (expected #{POLICIES.join(', ')})"
       end
 
       # -> :ok | :unauthorized | :disabled. A SYMBOL and not a Rack triple (the
-      # RFC sketched one): a status code is the transport's vocabulary, and keeping
+      # the design sketched one): a status code is the transport's vocabulary, and keeping
       # it out of here is what lets this class be tested without Rack and read
       # without knowing HTTP.
       def authenticate(req)
@@ -91,22 +132,28 @@ module Insika
       #   { "agent": "support", "external_id": "5511999998888",
       #     "event_id": "wamid.HBg…", "message": "queria saber do pedido",
       #     "vars": { … } }
+      #
+      # In SHADOW mode `event_id` is REQUIRED: it is the correlation key both
+      # halves of the pair are built from, and a mirror that cannot supply a
+      # stable id cannot be paired.
       def parse(_req, body:)
         body = body.is_a?(Hash) ? body : {}
         agent = string(body["agent"])
         external_id = string(body["external_id"])
         message = string(body["message"])
+        event_id = presence(body["event_id"])
 
         raise Insika::ValidationError, "agent is required" if agent.empty?
         raise Insika::ValidationError, "external_id is required" if external_id.empty?
         raise Insika::ValidationError, "message is required" if message.strip.empty?
+        raise Insika::ValidationError, "event_id is required in shadow mode" if @shadow && event_id.nil?
 
         vars = body["vars"].is_a?(Hash) ? body["vars"] : {}
         { agent: agent, external_id: external_id, message: message,
-          event_id: presence(body["event_id"]), vars: vars }
+          event_id: event_id, vars: vars, incumbent_reply: presence(body["incumbent_reply"]) }
       end
 
-      # RFC-0011 §4.3 — the engine namespaces the platform's conversation key, so a
+      # the engine namespaces the platform's conversation key, so a
       # Slack channel id and a phone number can never collide, an operator can see
       # where a conversation came from, and an id minted for one channel cannot be
       # used to read another's session.
@@ -127,6 +174,8 @@ module Insika
       # consumer that receives the same delivery twice (we retried after a timeout
       # that actually landed) can drop the second one.
       def deliver(payload, to:, delivery_id: nil)
+        raise Insika::DeliveryError, "relay '#{@id}' is in shadow mode and must never deliver" if @shadow
+
         raise Insika::DeliveryError, "relay deliver_url is not configured" if @deliver_url.empty?
 
         if (reason = egress_violation)
@@ -143,8 +192,33 @@ module Insika
         raise Insika::DeliveryError, "#{e.class}: #{e.message}"
       end
 
+      # The reply, as recorded by the mirror. Follows the
+      # same strictness as `parse`; `at` is optional (nil = now).
+      def parse_shadow_reply(_req, body:)
+        body = body.is_a?(Hash) ? body : {}
+        external_id = string(body["external_id"])
+        event_id = presence(body["event_id"])
+        reply = string(body["reply"])
+
+        raise Insika::ValidationError, "external_id is required" if external_id.empty?
+        raise Insika::ValidationError, "event_id is required" if event_id.nil?
+        raise Insika::ValidationError, "reply is required" if reply.strip.empty?
+
+        at = presence(body["at"])
+        raise Insika::ValidationError, "at must be an ISO8601 timestamp" if at && !parseable_time?(at)
+
+        { external_id: external_id, event_id: event_id, reply: reply, at: at }
+      end
+
       private
 
+      def parseable_time?(value)
+        Time.iso8601(value)
+        true
+      rescue ArgumentError
+        false
+      end
+
       # Resolved on EVERY call, not once at boot: a hostname that answered a public
       # address yesterday can answer 169.254.169.254 today, and this POST carries
       # the customer's conversation.

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

@@ -1,4 +1,4 @@
-// Insika web widget (RFC-0011 §5.2).
+// Insika web widget.
 //
 // One <script> tag, no framework, no build step, no dependency:
 //
@@ -176,7 +176,7 @@
   }
 
   // The engine issues the session id; we only ever store the one it gave us
-  // (RFC-0011 §4.3 — a client that proposes its own id on a public endpoint is
+  // (a client that proposes its own id on a public endpoint is
   // one enumeration away from reading someone else's conversation).
   function session() {
     var saved = remembered;

data/lib/insika/channels/web.rb

@@ -6,8 +6,8 @@ require "securerandom"
 
 module Insika
   module Channels
-    # The web widget (RFC-0011 §5) — the FIRST Shape A channel, and the adoption
-    # claim behind the whole RFC: an adopter pastes one tag into their site and has
+    # The web widget — the FIRST Shape A channel, and the adoption
+    # claim behind the whole design: an adopter pastes one tag into their site and has
     # a working agent, with no backend of their own and no build step.
     #
     #   <script src="https://agents.example.com/channels/web/asset/widget.js"
@@ -17,7 +17,7 @@ module Insika
     # no outbox, no claim and no `deliver` here — the three routes and a static
     # asset are the entire surface:
     #
-    #   POST /channels/web/sessions      mint an opaque session id (the engine's, §4.3)
+    #   POST /channels/web/sessions      mint an opaque session id (the engine's)
     #   POST /channels/web/messages      the turn, answered as SSE on this connection
     #   GET  /channels/web/asset/widget.js
     #
@@ -29,7 +29,7 @@ module Insika
     #   · an AGENT allowlist — a visitor addresses the agents the operator published
     #     to the widget, not every agent in the deployment;
     #   · an ORIGIN allowlist — exact match, no wildcards, and no "allow all" value;
-    #   · a mandatory chat RATE LIMIT (§5.4) — the channel answers `:disabled`
+    #   · a mandatory chat RATE LIMIT — the channel answers `:disabled`
     #     until one is configured, because a public endpoint with an LLM behind it
     #     and no ceiling is an unmetered bill waiting to happen.
     #
@@ -49,8 +49,8 @@ module Insika
       # An unversioned URL cannot be cached for a year — the next release would
       # never reach a browser that already has it. Short max-age + an ETag instead:
       # the common case is a 304 with no body, and an upgrade lands within minutes.
-      # (A deliberate narrowing of §5.2's "long-cache versioned URL": the install
-      # snippet in the RFC has no version in it, so there is nothing to bust.)
+      # (A deliberate narrowing of's "long-cache versioned URL": the install
+      # snippet has no version in it, so there is nothing to bust.)
       ASSET_CACHE_CONTROL = "public, max-age=300"
 
       attr_reader :id
@@ -67,7 +67,7 @@ module Insika
         new(origins: origins, agents: agents, id: id, chat_rate_limit: chat_rate_limit)
       end
 
-      # The probe §5.4's gate needs, asked exactly the way `EdgeLimiter` asks it at
+      # The probe's gate needs, asked exactly the way `EdgeLimiter` asks it at
       # turn time: the per-agent override first, the platform default second. Built
       # here so both composition roots wire the gate identically, and returned as a
       # lambda so the channel itself stays store-free.
@@ -149,7 +149,7 @@ module Insika
         { agent: agent, session_id: session_id, message: message }
       end
 
-      # §4.3's hard rule for a public channel: the ENGINE issues the id and the
+      #'s hard rule for a public channel: the ENGINE issues the id and the
       # client never proposes one. A visitor-supplied session id on an anonymous
       # endpoint is session hijacking by enumeration, so there is no create-on-write
       # path — `POST /messages` with an unknown id is a 404, not a new conversation.
@@ -159,7 +159,7 @@ module Insika
       # protocol: what to type, what to say while a tool runs, and how it ended.
       #
       # `:intermediate` and `:thinking` are deliberately absent. `:content` is the
-      # ANSWER (P19) — the model's narration on the way there is internal, and a
+      # ANSWER — the model's narration on the way there is internal, and a
       # widget that rendered it would show the customer the engine thinking out loud.
       def frame_for(event)
         case event.type

data/lib/insika/channels/webhook.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  module Channels
+    # A webhook as a Shape B "channel": the recipient of operator ALERTS
+    # (WS6). One instance per configured URL, registered in the ChannelRegistry
+    # so ChannelDelivery's outbox+claim+retry pipeline delivers the alert the
+    # same way it delivers a chat answer — at-most-once, bounded retry, boot
+    # sweep. Deliberately NOT Slack/CRM/anything: it POSTs the event as JSON and
+    # the consumer interprets it (the engine transports, it does not integrate).
+    #
+    # The target URL is operator configuration, so the POST crosses the SAME
+    # egress guard the Relay applies: https-only (fails closed), private/
+    # loopback/metadata targets and DNS-rebindable hosts blocked. Without it the
+    # `alerts.webhook` URL is an SSRF vector — a URL pointed at cloud metadata
+    # or an internal API exfiltrates alert events out of the boundary (WS6).
+    class Webhook
+      def initialize(url, http:, allow_http: false, allow_private: false)
+        @http = http
+        @allow_http = allow_http
+        @allow_private = allow_private
+      end
+
+      # The ChannelDelivery contract: -> HTTP status (200..299 = delivered).
+      # Every failure becomes a DeliveryError so the bounded retry records it.
+      def deliver(payload, to:, delivery_id: nil)
+        if (reason = egress_violation(to))
+          raise Insika::DeliveryError, "webhook egress blocked for #{to}: #{reason}"
+        end
+
+        result = @http.request(
+          method: :post, url: to,
+          headers: { "content-type" => "application/json" },
+          body: JSON.generate(payload)
+        )
+        result[:status].to_i
+      rescue Insika::DeliveryError
+        raise
+      rescue StandardError => e
+        raise Insika::DeliveryError, "webhook: #{e.message}"
+      end
+
+      private
+
+      # Resolved on EVERY delivery, not once at registration: a host that
+      # answered a public address yesterday can answer 169.254.169.254 today,
+      # and this POST carries the operator's alerts.
+      def egress_violation(url)
+        Insika::EgressGuard.violation(url, allow_http: @allow_http,
+                                           allow_private: @allow_private)
+      rescue URI::InvalidURIError
+        "invalid URL"
+      end
+    end
+  end
+end

data/lib/insika/chat_builder.rb

@@ -13,7 +13,9 @@ module Insika
   # Executor, injected as the `emit` callable.
   class ChatBuilder
     def initialize(tool_registry:, skill_catalog:, checkpoint_store:, event_stream:,
-                   hooks:, tool_catalog: nil, memory_store: nil, subagent_runner: nil)
+                   hooks:, tool_catalog: nil, memory_store: nil, subagent_runner: nil,
+                   tool_trace_store: nil, media_runner: nil, session_store: nil,
+                   contact_store: nil, followup_store: nil)
       @tool_registry = tool_registry
       @skill_catalog = skill_catalog
       @checkpoint_store = checkpoint_store
@@ -21,10 +23,25 @@ module Insika
       @hooks = hooks
       @tool_catalog = tool_catalog
       @memory_store = memory_store
-      # RFC-0010: the object exposing #run_subagent (the Executor). nil = the
+      # only to trace load_skill, which is not enveloped — nil = no trace (parity).
+      @tool_trace_store = tool_trace_store
+      # the object exposing #run_subagent (the Executor). nil = the
       # spawn_subagent system tool is never wired (parity for a builder used
       # without delegation, e.g. some unit stubs).
       @subagent_runner = subagent_runner
+      # the Executor as the generate_image/tts runner (seams + usage
+      # accounting). nil = the media tools are never wired (parity for stubs).
+      @media_runner = media_runner
+      # update_briefing / set_next_step are the briefing-write system
+      # tools — wired only with @session_store present AND profile.briefing_fields
+      # non-empty (double gate, like remember). nil = never wired (parity for a
+      # builder used without session persistence, e.g. some unit stubs).
+      @session_store = session_store
+      # the schedule/cancel_followup system tools — wired only
+      # with BOTH stores present AND a parsed follow-up policy on the profile
+      # (double gate, like remember). nil = never wired (parity).
+      @contact_store = contact_store
+      @followup_store = followup_store
     end
 
     # Configures an already-created chat with the context (stage 2) and the
@@ -69,9 +86,16 @@ module Insika
 
       # load_skill is a system default (outside the allowlist), otherwise
       # progressive disclosure breaks. allowed_skills comes from the Resolution
-      # (policy).
-      skill_names = Array(state.allowed_skills).map { |s| s.respond_to?(:name) ? s.name : s.to_s }
-      tools << Tools::LoadSkill.new(@skill_catalog, skill_names) unless skill_names.empty?
+      # (policy), minus the EAGER ones: their bodies are already in the prompt, so a
+      # call could only pay for a duplicate. Nothing lazy left -> the tool is not
+      # wired at all. Keeping it for the discretionary skills is deliberate: that
+      # call is the only record of which skill the model actually reached for.
+      skill_names = lazy_skill_names(state)
+      unless skill_names.empty?
+        tools << Tools::LoadSkill.new(@skill_catalog, skill_names,
+                                      trace_recorder: @tool_trace_store, state: state,
+                                      agent: state.profile.id)
+      end
 
       # remember is the memory-write system tool — wired only with
       # @memory_store present AND profile.memory (a double gate). Never enveloped.
@@ -80,24 +104,75 @@ module Insika
                                      event_stream: @event_stream, state: state)
       end
 
-      # spawn_subagent is the delegation system tool (RFC-0010) — wired only with a
+      # update_briefing / set_next_step are the briefing-write system tools
+      #  — wired only with @session_store present AND
+      # profile.briefing_fields non-empty (double gate, like remember). Never
+      # enveloped: deterministic in-process writes.
+      fields = if state.profile.respond_to?(:briefing_fields)
+                 Array(state.profile.briefing_fields).map(&:to_s)
+               else
+                 []
+               end
+      if @session_store && !fields.empty?
+        tools << Tools::UpdateBriefing.new(session_store: @session_store, fields: fields,
+                                           event_stream: @event_stream, state: state)
+        tools << Tools::UpdateBriefing::SetNextStep.new(session_store: @session_store,
+                                                        event_stream: @event_stream, state: state)
+      end
+
+      # signal_stuck is the "I cannot proceed" system tool (WS5) — wired only
+      # when the agent opted in (`profile.stuck_signal`), never enveloped. It is a
+      # deterministic signal; the consumer decides what "stuck" means. Defensive
+      # read: a minimal profile double without the reader means off (nil = parity).
+      if state.profile.respond_to?(:stuck_signal) && state.profile.stuck_signal
+        tools << Tools::StuckSignal.new(state: state)
+      end
+
+      # schedule/cancel_followup are the follow-up system tools  —
+      # wired only with BOTH stores present AND a parsed follow-up policy on
+      # the profile (double gate, like remember). Never enveloped: the store
+      # writes are deterministic. The tools stay OUT of the allowlist — they
+      # are data-driven per agent, not admittable (prompts/memory/stuck_signal
+      # are the precedent).
+      if @contact_store && @followup_store && followup_policy(state)
+        tools << Tools::ScheduleFollowup.new(contact_store: @contact_store,
+                                             followup_store: @followup_store,
+                                             state: state,
+                                             event_stream: @event_stream)
+        tools << Tools::CancelFollowup.new(followup_store: @followup_store,
+                                           state: state,
+                                           event_stream: @event_stream)
+      end
+
+      # generate_image / tts are the generated-media system tools (WS9, saída)
+      # — wired only when BOTH gates pass, never enveloped: the AGENT opted in
+      # (`profile.outputs` — the per-kind generator config) AND the CHANNEL
+      # declared it can receive the media (state.channel_capabilities, from the
+      # request's `channel.capabilities`). The "abstraction admits only what
+      # leaks" rule, C4: a channel that never declared image_output cannot get
+      # a generated image; a profile without `outputs` never generates. The
+      # runner is the Executor (seams + usage accounting); nil = no media
+      # output at all (parity for a stub builder).
+      output_media_tools(state).each { |tool| tools << tool } if @media_runner
+
+      # spawn_subagent is the delegation system tool — wired only with a
       # runner present AND profile.subagents non-empty (a double gate, like
       # remember). Never enveloped: in the synchronous mode the child lives in the
       # parent's envelope. The runtime gate on WHICH agent is spawnable is the
       # parent's subagents allowlist, enforced in Executor#run_subagent.
       if @subagent_runner && !Array(state.profile.subagents).empty?
         tools << Tools::Subagent.new(runner: @subagent_runner, state: state)
-        # ...and its parallel sibling (RFC-0010 §A): fan-out N children at once.
+        # and its parallel sibling: fan-out N children at once.
         tools << Tools::Subagents.new(runner: @subagent_runner, state: state)
       end
 
       unless tools.empty?
-        # Item 30: the ONLY place the gem is told to run tool calls in parallel.
+        # the ONLY place the gem is told to run tool calls in parallel.
         # `:fibers` is not a preference but the only admissible mode — `:threads`
         # breaks ToolEnvelope's `Async::Task.current.with_timeout`, the SQLite
         # store's fiber semaphore, and the turn's own durability (mailbox,
         # approvals, cancellation are all expressed in fiber terms). The number
-        # the operator configured is OUR cap (D4, ToolAssembly#install_tool_gate);
+        # the operator configured is OUR cap (ToolAssembly#install_tool_gate);
         # the gem has none.
         if tool_concurrency_for(state)
           chat.with_tools(*tools, concurrency: :fibers)
@@ -109,9 +184,47 @@ module Insika
       chat
     end
 
+    # The skills the model still has to ask for: the Resolution's set minus the eager
+    # ones. Intersected by NAME against the catalog's own verdict (SkillCatalog#eager_for)
+    # so the tool and the level-1 list can never disagree about who is eager. A catalog
+    # without the reader (a unit stub) falls back to the whole set — parity.
+    def lazy_skill_names(state)
+      names = Array(state.allowed_skills).map { |s| s.respond_to?(:name) ? s.name : s.to_s }
+      return names unless @skill_catalog.respond_to?(:eager_for)
+
+      eager = @skill_catalog.eager_for(state.profile).map(&:name)
+      names - eager
+    end
+
+    # the follow-up tools' gate — a PARSED policy on the profile.
+    # A malformed declaration reads as "no policy" (the firer blocks it, the
+    # doctor reports it; the tools are simply not offered).
+    def followup_policy(state)
+      followup = state.profile.respond_to?(:followup) ? state.profile.followup : nil
+      followup && Insika::FollowupPolicy.parse(followup)
+    end
+
+    # WS9 (saída): the media-output tools this turn may carry, per the double
+    # gate (profile outputs ∩ channel capabilities). [] = none. Defensive reads
+    # throughout — a minimal profile/state stub is "off", which is the safe
+    # parity reading.
+    def output_media_tools(state)
+      outputs = state.profile.respond_to?(:outputs) ? state.profile.outputs : nil
+      return [] unless outputs.is_a?(Hash)
+      return [] unless state.respond_to?(:channel_capabilities)
+
+      caps = Array(state.channel_capabilities).map(&:to_s)
+      image_cfg = outputs["image"]
+      tts_cfg = outputs["tts"]
+      [
+        (Tools::GenerateImage.new(runner: @media_runner, config: image_cfg, state: state) if image_cfg.is_a?(Hash) && caps.include?("image_output")),
+        (Tools::Tts.new(runner: @media_runner, config: tts_cfg, state: state) if tts_cfg.is_a?(Hash) && caps.include?("audio_output"))
+      ].compact
+    end
+
     # The turn's effective tool concurrency (nil = serial), plus the ONE thing the
     # gate owes the operator: when the profile asked for parallel tool calls and
-    # this turn silently cannot have them (D3 — an approval-required tool would
+    # this turn silently cannot have them (an approval-required tool would
     # deadlock two fibers on the single per-task mailbox), say so once. Otherwise
     # the speedup just vanishes with no reason given. The rule itself lives in
     # TurnState; a state predating those readers (a unit stub) means off.
@@ -137,7 +250,7 @@ module Insika
                          ))
     end
 
-    # §11 R3: opt-in Anthropic prompt caching. When the agent enables
+    # R3: opt-in Anthropic prompt caching. When the agent enables
     # prompt_caching AND the resolved provider is Anthropic, wrap the system in
     # the provider's native Content helper with cache: true — ONE breakpoint at
     # the END of the system block. By Anthropic's prefix order
@@ -176,7 +289,7 @@ module Insika
     # History comes from the context/checkpoint. The {role:, content:} shape
     # tolerates string keys (JSON from the stores). `flatten(1)` dissolves the
     # Session provider's "eviction units" (an assistant+tool_results cycle grouped
-    # as one Array, §11 R1) back into a flat message stream.
+    # as one Array, R1) back into a flat message stream.
     #
     # tool_calls / tool_call_id are rehydrated ONLY when present, so a message
     # without them keeps the 2-arg shape the specs' FakeChat expects (no unknown
@@ -216,6 +329,14 @@ module Insika
       tool_calls = 0
       max_tool_calls = state.profile.limits[:max_tool_calls] || 50
 
+      # 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) }
+                   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
+
       chat.before_tool_call do |tool_call|
         # call<->decorator correlation (side-effects/skip) — 1st line.
         state.current_tool_call = tool_call
@@ -224,9 +345,13 @@ module Insika
         tool_calls += 1
         if tool_calls > max_tool_calls
           raise Insika::TimeoutError.new("tool call limit exceeded (#{max_tool_calls})",
-                                          stage: :tool_limit)
+                                           stage: :tool_limit)
         end
 
+        # AFTER the count, BEFORE the call runs — a post-warning
+        # repeat raises here, so the stubborn loop pays for no extra call.
+        detector&.tool_call(tool_call.name, tool_call.arguments)
+
         # :tool pair: RubyLLM's callbacks are additive — the altered subject
         # feeds later hooks and the events, but does not rewrite the call the
         # model executes. A hook exception here aborts the turn.
@@ -246,9 +371,16 @@ module Insika
       end
 
       chat.after_tool_result do |result|
+        # 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)
         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
     end
   end
 end

data/lib/insika/checkpoint_store.rb

@@ -109,6 +109,22 @@ module Insika
       nil
     end
 
+    # Deletes EVERY checkpoint + side-effect record of the task (WS8 retention:
+    # a purged task's durability trail goes with it — no orphaned keys).
+    # -> count of records removed.
+    def purge(task_id)
+      removed = 0
+      checkpoint_turns(task_id).each do |n|
+        @store.delete(SCOPE, checkpoint_key(task_id, n))
+        removed += 1
+      end
+      sideeffect_turns(task_id).each do |n|
+        @store.delete(SCOPE, sideeffects_key(task_id, n))
+        removed += 1
+      end
+      removed
+    end
+
     private
 
     def checkpoint_key(task_id, turn)