insika 0.1.0 → 0.3.0

data/lib/insika/context/providers/briefing.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Read path for the session briefing: the per-session
+      # working-state the agent keeps and asks for. Thin adapter over the
+      # SessionStore, same pattern as Memory: one `:system` fragment,
+      # deterministic. The MISSING list is rendered, never implied — that list
+      # is what stops the model re-asking for a field already given.
+      class Briefing < ContextProvider
+        def initialize(session_store:)
+          @session_store = session_store
+        end
+
+        # Stable id -> the context-trace category "briefing".
+        def id = "briefing"
+
+        # Pack-declared: no briefing_fields -> no provider (the Builder still
+        # applies the `context_providers` allowlist on top — two gates, like Memory).
+        def enabled_for?(profile)
+          fields = profile.respond_to?(:briefing_fields) ? profile.briefing_fields : nil
+          !Array(fields).empty?
+        end
+
+        # required? == false (default): a store failure degrades via the Builder's
+        # warning path, never aborts the turn.
+        def call(request)
+          session = request.respond_to?(:session) ? request.session : nil
+          return [] if session.nil? # one-shot turns have no briefing
+
+          briefing = briefing_for(session)
+          fields = briefing["fields"] || {}
+          declared = Array(request.profile.briefing_fields)
+          return [] if declared.empty? # defensive; enabled_for? already gates
+
+          block = format_block(declared, fields, briefing["next_step"])
+          return [] if block.nil?
+
+          [ContextFragment.build(content: block, placement: :system,
+                                 priority: Context::Priority::BRIEFING,
+                                 source: id)]
+        end
+
+        private
+
+        # Re-reads the briefing from the store, like the Session provider: the
+        # persisted record is the source of truth, not the request's turn-start
+        # snapshot. A read failure propagates to the Builder, which degrades it
+        # to a :provider_warning (required? == false).
+        def briefing_for(session)
+          @session_store.find(session.id)&.briefing || {}
+        end
+
+        # Byte contract (the specs assert this shape):
+        #   <briefing>
+        #   known:
+        #     size: M
+        #   still missing: delivery_day
+        #   next step: send the payment link tomorrow at 10
+        #   </briefing>
+        # Rules: `known` renders only when at least one declared field has a
+        # stored value; `still missing` renders every declared field with no
+        # stored value (including the all-missing case — that is the block's
+        # job); `next step` renders only when non-nil; stored keys NOT in the
+        # declaration are never rendered (they stay in the store and reappear if
+        # the pack re-declares them).
+        def format_block(declared, fields, next_step)
+          known = declared.filter_map do |name|
+            "  #{name}: #{flatten(fields[name])}" if Coercion.present?(fields[name])
+          end
+          missing = declared.reject { |name| Coercion.present?(fields[name]) }
+
+          lines = []
+          lines << "known:" unless known.empty?
+          lines.concat(known)
+          lines << "still missing: #{missing.join(', ')}" unless missing.empty?
+          lines << "next step: #{flatten(next_step)}" if Coercion.present?(next_step)
+          return nil if lines.empty?
+
+          <<~BLOCK.strip
+            <briefing>
+            #{lines.join("\n")}
+            </briefing>
+          BLOCK
+        end
+
+        # utf8 the value and flatten newlines/whitespace so a value can never
+        # break the block's line structure.
+        def flatten(value)
+          Coercion.utf8(value.to_s).gsub(/\s+/, " ").strip
+        end
+      end
+    end
+  end
+end

data/lib/insika/context/providers/memory.rb

@@ -20,7 +20,7 @@ module Insika
         # required? == false (default): a failure (store unavailable) becomes a
         # :provider_warning + graceful degradation — never aborts the turn.
         def call(request)
-          tenant = memory_tenant(request)
+          tenant = memory_scope(request)
           facts = @store.facts(tenant: tenant)
           notes = @store.notes(tenant: tenant, limit: @notes_limit)
           return [] if facts.empty? && notes.empty?
@@ -33,15 +33,24 @@ module Insika
 
         private
 
-        # Engine memory scope (D3): an EXPLICIT tenant from the Command wins
-        # (multi-merchant override); otherwise the SESSION (=chat) — engine-owner
-        # memory is per-chat. No session (one-shot) and no tenant -> nil (MemoryStore
-        # applies _default). Symmetric to the write path (`state.tenant` in the Executor).
-        def memory_tenant(request)
+        # Engine memory scope (WS8): the request's CUSTOMER-scoped cell
+        # ("[tenant:]customer" — engine-owner memory is per customer, never per
+        # tenant) wins; otherwise an EXPLICIT tenant from the Command (the
+        # multi-merchant override); otherwise the SESSION (=chat), MARKED like
+        # the write path ("chat:<session id>" —  : a session cell is
+        # never a bare cell, so the drill cannot read a conversation as a
+        # customer). No session (one-shot) and no tenant -> nil (MemoryStore
+        # applies _default). Symmetric to the write path (`state.tenant` in the
+        # Executor).
+        def memory_scope(request)
+          scoped = request.respond_to?(:memory_scope) ? request.memory_scope : nil
+          return scoped if scoped
+
           explicit = request.respond_to?(:tenant) ? request.tenant : nil
           return explicit if explicit
 
-          request.respond_to?(:session) ? request.session&.id : nil
+          session = request.respond_to?(:session) ? request.session : nil
+          session && session.id ? "#{Insika::MemoryStore::SESSION_TAG}:#{session.id}" : nil
         end
 
         # Passive <memory> (no instruction — the HOW of writing lives in the `remember` tool).

data/lib/insika/context/providers/prompt.rb

@@ -10,11 +10,26 @@ module Insika
       #
       # PER-AGENT identity. `profile.prompt_files` (file names)
       # wins over the wiring's `files:` — this fixes the limitation of a new
-      # agent inheriting Bia's prompt. The content comes from `agent_files`
+      # agent inheriting the previous persona's prompt. The content comes from `agent_files`
       # (AgentFileStore, lives in the Store), with a File.read fallback
       # for on-disk paths (compat/seed). Without prompt_files -> uses the wiring's
       # `files:` (deployment default; byte-for-byte parity).
       class Prompt < ContextProvider
+        # Engine-owned execution discipline, appended AFTER the agent's identity.
+        # The one behavior every reference harness bakes into its base prompt
+        # (OpenClaw's "Execution Bias") and this engine was missing: a weak tool
+        # result read as final. A constant — byte-identical every turn, so
+        # prompt_caching pays ONE write on the deploy that introduces it, never
+        # per turn. Opt-out per profile (`tool_persistence false`), the single
+        # default-ON profile flag: the proven-good behavior is the default, the
+        # exception is the thing an operator declares.
+        TOOL_PERSISTENCE = "## Tool discipline\n" \
+          "- Weak or empty tool result: try again with a different approach — rephrase the " \
+          "query, use a synonym or broader term, drop a secondary filter — before telling " \
+          "the user you found nothing. Do not narrate the retries. Then conclude.\n" \
+          "- Tool error: read the error, fix the arguments or try another path; never " \
+          "repeat the exact same call."
+
         def initialize(base: "", files: [], catalog: nil, agent_files: nil, system_files: nil)
           @base = base
           @files = Array(files)
@@ -24,6 +39,8 @@ module Insika
         end
 
         def required? = true
+        # identity (config/agent-file derived — already pinned).
+        def layer = :identity
 
         def call(request)
           fragments = []
@@ -62,7 +79,18 @@ module Insika
           else
             sources.each { |src| parts << read_source(profile&.id, src.to_s) }
           end
-          parts.reject { |p| p.nil? || p.strip.empty? }.join("\n\n")
+          identity = parts.reject { |p| p.nil? || p.strip.empty? }.join("\n\n")
+          # Discipline rides an EXISTING identity, never substitutes one: an
+          # agent with no identity at all must stay detectably empty.
+          return identity if identity.empty? || !tool_persistence?(profile)
+
+          "#{identity}\n\n#{TOOL_PERSISTENCE}"
+        end
+
+        # nil/absent/true = ON (the engine default); only an explicit `false`
+        # turns it off. Defensive respond_to?: a minimal profile stub reads ON.
+        def tool_persistence?(profile)
+          !(profile.respond_to?(:tool_persistence) && profile.tool_persistence == false)
         end
 
         # GLOBAL system files: apply to every agent,

data/lib/insika/context/providers/request.rb

@@ -13,7 +13,7 @@ module Insika
           # "history" is transcript (consumed by the Session provider), not turn
           # metadata — it does not leak into the system's request_context. Keys
           # prefixed with "__" are INTERNAL slots (e.g. the per-chat model pin
-          # "__llm__", §10) — reserved, never rendered to the model.
+          # "__llm__") — reserved, never rendered to the model.
           request.vars.to_h.each do |k, v|
             next if k.to_s == "history" || k.to_s.start_with?("__")
 

data/lib/insika/context/providers/session.rb

@@ -17,7 +17,13 @@ module Insika
           messages = transcript_for(request)
           return [] if messages.nil? || messages.empty?
 
-          # 1 fragment per EVICTION UNIT (§11 R1): a plain message, OR an
+          # A3/C3 opt-in: identical tool results in the transcript collapse to a
+          # back-reference (the cheap half of compaction). CHANGES WHAT THE MODEL
+          # SEES — hence the profile flag, never a default. Applied BEFORE the
+          # eviction-unit grouping so a cycle's results are already slim.
+          messages = compress_history(messages, request)
+
+          # 1 fragment per EVICTION UNIT (R1): a plain message, OR an
           # assistant-with-tool_calls together with its tool results. Grouping at
           # the fragment level means the budget cut (apply_budget) drops a whole
           # tool cycle atomically — a tool_use is NEVER seeded without its result
@@ -72,7 +78,16 @@ module Insika
           h
         end
 
-        def tool_calls?(msg) = msg[:tool_calls] && !Array(msg[:tool_calls]).empty?
+                def tool_calls?(msg) = msg[:tool_calls] && !Array(msg[:tool_calls]).empty?
+
+        # The compression is opt-in per agent (profile data, config-over-code):
+        # absent/off -> the transcript passes through byte-identical (parity).
+        def compress_history(messages, request)
+          profile = request.respond_to?(:profile) ? request.profile : nil
+          return messages unless profile&.tool_output_compression
+
+          ToolOutputCompressor.compress_transcript(messages)
+        end
 
         # Precedence: checkpoint -> explicit history -> store.
         # The first present source wins; no merge.

data/lib/insika/context/providers/skill.rb

@@ -10,10 +10,16 @@ module Insika
       class Skill < CatalogProvider
         # priority 80: above deferred tools (70), below pinned identity.
         def priority = Context::Priority::SKILL
+        # catalog + allowlist — config only.
+        def layer = :identity
 
         private
 
-        def entries(request) = @catalog.effective(request.profile.skills)
+        # Only the skills the model still has to ASK for. An eager skill is already in
+        # the prompt in full, so advertising it here would invite a `load_skill` call
+        # that buys a duplicate — and the catalog's whole job is to describe what is
+        # NOT yet loaded. Nothing lazy left -> CatalogProvider emits no fragment.
+        def entries(request) = @catalog.lazy_for(request.profile)
       end
     end
   end

data/lib/insika/context/providers/skill_trigger.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Level-2 skill BODIES in the prompt, with two selection modes — both
+      # deterministic, neither asks the model:
+      #
+      #   profile.skills_eager  -> the agent's eager set (all, or a named list),
+      #                            every turn. No decision at all, so no miss rate.
+      #                            Costs the bodies' tokens.
+      #   `triggers:` in the    -> only the skills whose trigger matches this
+      #   frontmatter              message (whole word, accent- and case-insensitive).
+      #
+      # Model-invoked loading (load_skill) stays the fallback for everything else.
+      #
+      # A trigger only belongs on a skill that can COMPLETE the turn by itself.
+      # Injecting a reference table whose companion skill holds the procedure is
+      # worse than injecting nothing: the model has a plausible half-recipe in the
+      # prompt, so it never calls load_skill for the other half. Measured on a real
+      # pack — the line map arrived, the query-construction rules did not, and the
+      # searches came out malformed.
+      # Activation here is NOT a tool call, so nothing in the transcript would show
+      # it. The fragment's `labels` carry the name AND THE REASON, and the EXECUTOR
+      # announces them (:skill_activated) — not this provider. A provider only has the
+      # ContextRequest, which has no task, and the Studio's SSE drops an event whose
+      # meta lacks `task_id` when the subscriber is task-scoped (Subscription#matches?):
+      # emitting from here produced an event that was correct and never arrived.
+      class SkillTrigger < ContextProvider
+        def initialize(catalog:)
+          @catalog = catalog
+        end
+
+        def call(request)
+          matched = select(request)
+          return [] if matched.empty?
+
+          content = matched.map do |skill, _reason|
+            %(<active_skill name="#{skill.name}">\n#{skill.body}\n</active_skill>)
+          end.join("\n\n")
+
+          labels = matched.map { |skill, reason| { "name" => skill.name, "reason" => reason } }
+          [ContextFragment.build(content: content, placement: :system,
+                                 priority: Context::Priority::SKILL_BODY, source: id,
+                                 labels: labels)]
+        end
+
+        private
+
+        # -> [[skill, reason]]. Two independent reasons a body lands here: the AGENT
+        # marked it eager (always), or a `triggers:` entry matched THIS message.
+        # The union is injected; everything else stays at level 1 for load_skill, where
+        # the model's call is the only record of what it reached for.
+        #
+        # The reason travels with the skill from here to the activation card, because
+        # "which skills were active" without "why each one was" is the information the
+        # deterministic paths destroyed when they replaced the load_skill call.
+        def select(request)
+          eager = @catalog.eager_for(request.profile).map { |skill| [skill, "eager"] }
+          # `triggered` reads the LAZY set, which excludes the eager one — so a skill
+          # cannot arrive twice. uniq_by name anyway: the invariant is worth not
+          # depending on from here.
+          selected = (eager + triggered(request)).uniq { |skill, _reason| skill.name }
+          (selected + companions(selected, request)).uniq { |skill, _reason| skill.name }
+        end
+
+        # Declared `companions:` travel with whatever brought them, so the half-recipe
+        # state cannot be assembled: the line map that arrived by trigger takes its
+        # query-construction rules with it. ONE LEVEL, deliberately — a transitive walk
+        # would make a cycle a hang and a chain a budget blowout, and "cannot work
+        # without" is a direct relationship.
+        #
+        # Restricted to the agent's own allowed set: a companion the agent cannot see
+        # is not injectable, and `doctor` flags that declaration rather than the engine
+        # quietly widening the allowlist.
+        def companions(selected, request)
+          wanted = selected.flat_map { |skill, _reason| Array(skill.companions).map { |c| [c.to_s, skill.name] } }
+          return [] if wanted.empty?
+
+          by_name = @catalog.effective(request.profile.skills, agent: request.profile.id)
+                            .each_with_object({}) { |s, acc| acc[s.name] = s }
+          wanted.filter_map do |name, of|
+            skill = by_name[name]
+            [skill, "companion:#{of}"] if skill
+          end
+        end
+
+        def triggered(request)
+          message = fold(request.message)
+          return [] if message.empty?
+
+          @catalog.lazy_for(request.profile).filter_map do |skill|
+            phrase = matched_trigger(skill, message)
+            [skill, "trigger:#{phrase}"] if phrase
+          end
+        end
+
+        # The trigger phrase that fired, or nil. AS AUTHORED, never as typed: the
+        # reason lands on the activation card, and what an operator needs there is the
+        # config line they can go and edit — not an echo of the customer's message
+        # (which also keeps the label content-free, like the rest of the trace).
+        #
+        # Two hygiene rules, and both are tokenization rather than the semantic
+        # matching this feature deliberately does not do:
+        #
+        #   whole word — bare substring made `triggers: presente` fire inside
+        #   *apresente*, and the card now PRINTS the matched phrase: `trigger:presente`
+        #   on a turn about *apresentação* would discredit the card on day one.
+        #
+        #   folded accents — the corpus is Portuguese and customers type *maquiagem*
+        #   and *maquiágem* unpredictably, so both sides are folded before comparing.
+        def matched_trigger(skill, folded_message)
+          skill.triggers.find do |trigger|
+            needle = fold(trigger)
+            next false if needle.empty?
+
+            /(?<![[:alnum:]])#{Regexp.escape(needle)}(?![[:alnum:]])/.match?(folded_message)
+          end
+        end
+
+        # NFD splits an accented letter into letter + combining mark; dropping the
+        # marks (\p{Mn}) leaves the bare letter, so "maquiágem" and "maquiagem" fold
+        # to the same string.
+        def fold(text) = text.to_s.unicode_normalize(:nfd).gsub(/\p{Mn}/, "").downcase
+      end
+    end
+  end
+end

data/lib/insika/context/providers/tool_search.rb

@@ -10,6 +10,8 @@ module Insika
       class ToolSearch < CatalogProvider
         # priority 70: below skills (80) in the sacrifice order.
         def priority = Context::Priority::TOOL_SEARCH
+        # tool registry + tools_deferred — config only.
+        def layer = :identity
 
         private
 

data/lib/insika/context_trace_store.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Insika
+  # Per-session CONTEXT trace, for the Studio's breakdown-by-category card
+  # One record per session in the raw backend (scope
+  # "context_traces") — RUNTIME data, next to sessions/tasks, like the
+  # ToolTraceStore it mirrors. A capped LIST of entries, ONE PER TURN, written
+  # by the Executor after tool assembly.
+  #
+  # Unlike the tool trace there is NO security machinery here by construction:
+  # the entry is counts and provider ids only (category -> tokens/fragments/
+  # pinned, the tools estimate, the budget verdict) — never fragment content,
+  # so there is nothing to mask. `record` still rescues everything: the trace
+  # NEVER breaks the turn.
+  class ContextTraceStore
+    SCOPE = "context_traces"
+    MAX_PER_SESSION = 50 # one per turn; turns are the unit, not tool calls
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Writes an entry into the session — UPSERT by (task_id, turn): a turn that
+    # suspends (approval) and resumes re-runs the context stage, and the
+    # re-record replaces the first one instead of duplicating it. (`turn` is
+    # 1-based PER TASK, so the task is part of the key.) Missing session_id ->
+    # no-op. -> the sanitized entry (parks it on TurnState for the
+    # stage-8 cache merge).
+    def record(session_id:, entry:)
+      sid = session_id.to_s
+      return if sid.empty?
+
+      e = sanitize(entry)
+      key = [e["task_id"], e["turn"]]
+      list = (@store.get(SCOPE, sid) || []).reject { |x| [x["task_id"], x["turn"]] == key } + [e]
+      @store.set(SCOPE, sid, list.last(MAX_PER_SESSION))
+      e
+    rescue StandardError
+      nil
+    end
+
+    # -> [Hash] session entries in chronological order. [] if none.
+    def for_session(session_id) = @store.get(SCOPE, session_id.to_s) || []
+
+    # Discards a session's trace (cleanup). -> bool (did it exist?).
+    def clear(session_id) = @store.delete(SCOPE, session_id.to_s)
+
+    private
+
+    # Keeps only the known shape; coerces numbers and strings so a caller bug
+    # degrades the card instead of poisoning the record.
+    def sanitize(entry)
+      e = entry.is_a?(Hash) ? entry : {}
+      categories = e[:categories] || e["categories"] || {}
+      tools = e[:tools] || e["tools"] || {}
+      {
+        "task_id" => (e[:task_id] || e["task_id"]).to_s,
+        "turn" => int(e[:turn] || e["turn"]),
+        "at" => (e[:at] || e["at"]).to_s,
+        "cap" => int(e[:cap] || e["cap"]),
+        "used" => int(e[:used] || e["used"]),
+        "evicted" => Array(e[:evicted] || e["evicted"]).map(&:to_s),
+        "categories" => categories.each_with_object({}) do |(name, c), acc|
+          c = {} unless c.is_a?(Hash)
+          cat = { "tokens" => int(c[:tokens] || c["tokens"]),
+                  "fragments" => int(c[:fragments] || c["fragments"]),
+                  "pinned" => int(c[:pinned] || c["pinned"]) }
+          # which cache layer the category belongs to ("identity" |
+          # "volatile"). Absent for a category recorded before the contract (or
+          # one that never learned it) — the view guards on nil.
+          layer = c[:layer] || c["layer"]
+          cat["layer"] = layer.to_s if layer
+          # WHAT the category carried and WHY ({name, reason}) — still ids only, so
+          # the no-masking-needed contract above holds. Omitted when empty: most
+          # categories have nothing to name and an empty key is just noise.
+          labels = normalize_labels(c[:labels] || c["labels"])
+          cat["labels"] = labels unless labels.empty?
+          acc[name.to_s] = cat
+        end,
+        "tools" => { "count" => int(tools[:count] || tools["count"]),
+                     "tokens" => int(tools[:tokens] || tools["tokens"]) },
+        "fingerprints" => fingerprints_of(e[:fingerprints] || e["fingerprints"]),
+        "cache" => cache_of(e[:cache] || e["cache"])
+      }.compact
+    end
+
+    # { name => sha256-hex }; names stringified, non-strings
+    # dropped. Absent when the caller passed nothing (a trace recorded before
+    # this feature has no key and the view guards on nil).
+    def fingerprints_of(raw)
+      return nil unless raw.is_a?(Hash) && !raw.empty?
+
+      raw.each_with_object({}) do |(name, hex), acc|
+        acc[name.to_s] = hex.to_s if hex.is_a?(String)
+      end.then { |h| h.empty? ? nil : h }
+    end
+
+    # { hit_pct, cached_tokens, prompt_tokens, invalidation_reason }.
+    # Unknown keys dropped. Present only when the caller passed it.
+    def cache_of(raw)
+      return nil unless raw.is_a?(Hash)
+
+      c = {
+        "hit_pct" => int_or_nil(raw[:hit_pct] || raw["hit_pct"]),
+        "cached_tokens" => int(raw[:cached_tokens] || raw["cached_tokens"]),
+        "prompt_tokens" => int(raw[:prompt_tokens] || raw["prompt_tokens"]),
+        "invalidation_reason" => raw[:invalidation_reason] || raw["invalidation_reason"]
+      }
+      c["invalidation_reason"] = c["invalidation_reason"].to_s unless c["invalidation_reason"].nil?
+      c
+    end
+
+    # Labels are {name, reason} in string keys (ContextFragment.label). A bare string
+    # still reads as a nameless-reason label: an entry recorded before reasons existed,
+    # or a caller that only has the id, degrades the card instead of poisoning it.
+    def normalize_labels(raw)
+      Array(raw).filter_map do |label|
+        name, reason = label.is_a?(Hash) ? [label[:name] || label["name"], label[:reason] || label["reason"]] : [label, nil]
+        next if name.to_s.empty?
+
+        { "name" => name.to_s, "reason" => reason&.to_s }.compact
+      end.uniq
+    end
+
+    def int(value) = Integer(value || 0)
+    def int_or_nil(value) = value.nil? ? nil : Integer(value)
+  end
+end

data/lib/insika/delegation_store.rb

@@ -4,8 +4,8 @@ require "securerandom"
 require "time"
 
 module Insika
-  # Durable record of an ASYNC delegation (RFC-0010 §5, item 21 Phase 2, hermes
-  # "delegation durability"). The synchronous subagent (Phase 1) needs no
+  # Durable record of an ASYNC delegation (hermes
+  # "delegation durability"). The synchronous subagent needs no
   # record — it lives and dies inside the parent's turn. The ASYNC subagent does:
   # the parent DISPATCHES and its turn ends; the child runs independently; when the
   # child finishes, its result is delivered to the parent as a NEW turn (never