insika 0.3.0 → 0.8.0

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,9 +17,14 @@ 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)
+      KNOWLEDGE    = 77  # <knowledge> top-K learned concepts (Knowledge) —
+                         #   below curated skills, above a single conversation's memory
       MEMORY       = 75  # <memory> read path (Memory)
       TOOL_SEARCH  = 70  # <available_tools> level 1 (ToolSearch)
       BRIEFING     = 65  # <briefing> session working state (Briefing) — D5:
@@ -27,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

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

@@ -5,9 +5,20 @@ module Insika
     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.
+      # SessionStore, same pattern as Memory, deterministic. The MISSING list is
+      # rendered, never implied — that list is what stops the model re-asking
+      # for a field already given.
+      #
+      # TWO fragments, and the split is the whole point:
+      #   · `<briefing>` (:system) — the DURABLE facts, what is already known.
+      #     Head of the prompt, where reference material belongs.
+      #   · `<recitation>` (:tail) — what is still missing and what the next step
+      #     is, rendered AFTER the whole history, as the last thing before the
+      #     current user message.
+      # Attention is strongest at the END of the context: a goal stated only in
+      # the head is the first thing a 30-call turn forgets. The recitation lives
+      # in exactly one place — it was MOVED out of the head, never duplicated, so
+      # a turn pays for it once.
       class Briefing < ContextProvider
         def initialize(session_store:)
           @session_store = session_store
@@ -34,12 +45,10 @@ module Insika
           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?
+          missing = declared.reject { |name| Coercion.present?(fields[name]) }
+          next_step = briefing["next_step"]
 
-          [ContextFragment.build(content: block, placement: :system,
-                                 priority: Context::Priority::BRIEFING,
-                                 source: id)]
+          [head_fragment(declared, fields), tail_fragment(missing, next_step)].compact
         end
 
         private
@@ -52,37 +61,57 @@ module Insika
           @session_store.find(session.id)&.briefing || {}
         end
 
-        # Byte contract (the specs assert this shape):
+        # The HEAD block — durable facts only. Byte contract:
         #   <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)
+        # Nothing known yet -> no fragment at all (an empty `known:` header
+        # teaches the model nothing and still costs a cache invalidation).
+        # Stored keys NOT in the declaration are never rendered (they stay in the
+        # store and reappear if the pack re-declares them).
+        def head_fragment(declared, fields)
           known = declared.filter_map do |name|
             "  #{name}: #{flatten(fields[name])}" if Coercion.present?(fields[name])
           end
-          missing = declared.reject { |name| Coercion.present?(fields[name]) }
+          return nil if known.empty?
 
+          block = <<~BLOCK.strip
+            <briefing>
+            known:
+            #{known.join("\n")}
+            </briefing>
+          BLOCK
+          ContextFragment.build(content: block, placement: :system,
+                                priority: Context::Priority::BRIEFING, source: id)
+        end
+
+        # The TAIL recitation — two lines, no more. Byte contract:
+        #   <recitation>
+        #   still missing: delivery_day
+        #   next step: send the payment link tomorrow at 10
+        #   </recitation>
+        # `still missing` renders every declared field with no stored value
+        # (including the all-missing case — that is this block's job); `next step`
+        # renders only when non-nil. Neither -> no fragment.
+        #
+        # A `user` message, like every other engine append inside a turn
+        # (LoopDetector, TurnBudget): the system prefix stays byte-stable, so the
+        # cache breakpoint at its end keeps hitting.
+        def tail_fragment(missing, next_step)
           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>
+          block = <<~BLOCK.strip
+            <recitation>
             #{lines.join("\n")}
-            </briefing>
+            </recitation>
           BLOCK
+          ContextFragment.build(content: { role: :user, content: block },
+                                placement: :tail,
+                                priority: Context::Priority::RECITATION, source: id)
         end
 
         # utf8 the value and flatten newlines/whitespace so a value can never

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

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Level 1 (progressive disclosure) of what the engine has LEARNED, as
+      # opposed to what a human curated (Skill) or the model wrote mid-turn
+      # (Memory). Retrieval is per-message and dynamic, so — like
+      # `SkillTrigger`, unlike the static `CatalogProvider` subclasses — this
+      # builds its `<knowledge>` block directly in `call`, never a fixed list.
+      class Knowledge < ContextProvider
+        def initialize(store:)
+          @store = store
+          # One Index PER TYPE, built once and reused for every agent/turn —
+          # never per call. This provider instance itself lives for the
+          # process's lifetime (built once at boot, see wiring), so an
+          # Index rebuilt fresh each call would throw away its own read
+          # cache (Index::Scan's dominant cost is re-parsing YAML
+          # frontmatter; measured, not assumed) on every single turn.
+          # Keyed by the config's `index` string so a future FTS5 agent
+          # gets its own instance, never Scan's.
+          @indexes = Hash.new { |h, index_name| h[index_name] = Insika::Knowledge::Index.build({ "index" => index_name }, store: @store) }
+        end
+
+        # Per-agent opt-in (`knowledge.retrieve`), like Memory's `profile.memory`.
+        def enabled_for?(profile) = !!(profile.knowledge && Coercion.truthy?(profile.knowledge["retrieve"]))
+
+        # required? == false (default): a store failure degrades to a
+        # :provider_warning, never aborts the turn.
+        def call(request)
+          config = request.profile.knowledge
+          return [] unless config
+
+          top_k = positive_int(config["top_k"]) || 5
+          index = @indexes[config["index"].to_s]
+          matches = index.search(request.profile.id, tenant: request.tenant,
+                                 query: request.message.to_s, top_k: top_k)
+          return [] if matches.empty?
+
+          hits = matches.map { |c| [c, "top-K match"] } +
+                 expand_links(matches, request, top_k).map { |c| [c, "one-hop link"] }
+
+          [ContextFragment.build(
+            content: format_block(hits), placement: :system,
+            priority: Context::Priority::KNOWLEDGE, source: id,
+            labels: hits.map { |c, reason| { "name" => c[:name], "reason" => reason } }
+          )]
+        end
+
+        private
+
+        def positive_int(value)
+          n = value.to_i
+          n.positive? ? n : nil
+        end
+
+        # ONE level, deliberately — the same "cannot work without" reasoning
+        # `SkillTrigger#companions` applies to a skill's declared companions:
+        # a transitive walk would make a cycle a hang and a chain a budget
+        # blowout. Newly-discovered concepts (not already in the top-K) are
+        # capped at top_k again — "that one hop is the whole graph benefit at
+        # ~1% of the graph cost", not a second unbounded retrieval.
+        def expand_links(matches, request, top_k)
+          known = matches.map { |c| c[:name] }
+          discovered = []
+          matches.each do |concept|
+            Insika::Knowledge::Concept.links(concept[:body]).each do |name|
+              next if known.include?(name) || discovered.any? { |d| d[:name] == name }
+
+              found = fetch(request, name)
+              discovered << found if found
+            end
+          end
+          discovered.first(top_k)
+        end
+
+        def fetch(request, name)
+          raw = @store.get(request.profile.id, name, tenant: request.tenant)
+          raw && Insika::Knowledge::Concept.parse(raw)
+        end
+
+        # Level 1 only — name/description/confidence/provenance, never the
+        # body (that is `load_knowledge`'s job). The instruction is the exact
+        # lesson the knowledge-adoption experiment drew: a polite "when to
+        # use" scored near zero; an explicit, ordered rule naming the tool
+        # held up. Present only when there is something to point at.
+        def format_block(hits)
+          entries = hits.map do |c, _reason|
+            %(  <concept name="#{c[:name]}" confidence="#{format('%.2f', c[:confidence])}" ) +
+              %(provenance="#{c[:provenance]}">#{c[:description]}</concept>)
+          end.join("\n")
+
+          <<~BLOCK.strip
+            <knowledge>
+            #{entries}
+            </knowledge>
+
+            If the customer's question needs more than the summary above, call
+            `load_knowledge("name")` FIRST — before any other lookup for that
+            topic. This is learned from past conversations, not official
+            policy: never state a `provenance="observed"` concept to the
+            customer as a guarantee.
+          BLOCK
+        end
+      end
+    end
+  end
+end

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

@@ -8,12 +8,16 @@ module Insika
       # a WRONG agent, not a degraded one. prompt_refs: priority 90 pinned
       # fragments, from the PromptCatalog (catalog defaults to nil).
       #
-      # PER-AGENT identity. `profile.prompt_files` (file names)
-      # wins over the wiring's `files:` — this fixes the limitation of a new
-      # 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).
+      # PER-AGENT identity, from `profile.prompt_files`/`base_prompt` only — an
+      # agent that declares neither has no identity here, and there is no
+      # deployment-wide fallback file to borrow one from. A shared fallback
+      # (a prior design: an agent without prompt_files silently inherited a
+      # wiring-level default) is exactly how a real deployment answered as the
+      # WRONG business: a `copilot` data agent provisioned without its own
+      # identity inherited the deployment's demo persona ("Bia, Pizzaria do
+      # Zé") byte for byte, confirmed live. An agent never wears another
+      # agent's identity — `@base`/`system_files` stay legitimate (the same
+      # generic content for every agent, never one agent's specific persona).
       class Prompt < ContextProvider
         # Engine-owned execution discipline, appended AFTER the agent's identity.
         # The one behavior every reference harness bakes into its base prompt
@@ -28,11 +32,12 @@ module Insika
           "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."
+          "repeat the exact same call.\n" \
+          "- A URL in a tool result (e.g. a `url` field): quote it byte-for-byte. Never " \
+          "construct, guess, or rewrite the domain, host, or path."
 
-        def initialize(base: "", files: [], catalog: nil, agent_files: nil, system_files: nil)
+        def initialize(base: "", catalog: nil, agent_files: nil, system_files: nil)
           @base = base
-          @files = Array(files)
           @catalog = catalog
           @agent_files = agent_files
           @system_files = system_files
@@ -43,12 +48,18 @@ module Insika
         def layer = :identity
 
         def call(request)
-          fragments = []
           identity = build_identity(request.profile)
-          unless identity.empty?
-            fragments << ContextFragment.build(content: identity, placement: :system,
-                                               priority: Context::Priority::IDENTITY, source: id, pinned: true)
+          if identity.empty?
+            raise ContextError.new(
+              "agent '#{request.profile&.id}' has no identity of its own (no base_prompt, " \
+              "no prompt_files) — refusing to run rather than answer with no identity or " \
+              "another agent's",
+              provider: id
+            )
           end
+
+          fragments = [ContextFragment.build(content: identity, placement: :system,
+                                             priority: Context::Priority::IDENTITY, source: id, pinned: true)]
           fragments.concat(ref_fragments(request.profile))
           fragments
         end
@@ -59,10 +70,9 @@ module Insika
         # A SINGLE fragment preserves the internal base->files order (sorting
         # acts only BETWEEN fragments) and guarantees byte-for-byte parity.
         #
-        # profile.prompt_files (names) wins over @files (wiring): an agent with
-        # its own identity does not inherit the deployment's. Each source resolves
-        # via AgentFileStore (per agent) OR File.read (on-disk path) — in that
-        # order. Without prompt_files, falls back to the wiring's @files.
+        # profile.prompt_files: each source resolves via AgentFileStore (per
+        # agent) OR File.read (on-disk path) — in that order. No other agent's
+        # files are ever read for this one; there is no wiring-level fallback.
         def build_identity(profile)
           parts = [@base]
           parts.concat(system_parts) # global system files, for EVERY agent
@@ -73,15 +83,11 @@ module Insika
           # NO identity at all, and a chatty model answered plausibly enough to hide
           # it. Additive to prompt_files, not exclusive: an agent may carry both.
           parts << profile&.base_prompt.to_s
-          sources = Array(profile&.prompt_files)
-          if sources.empty?
-            @files.each { |f| parts << File.read(f, encoding: "UTF-8") if File.exist?(f) }
-          else
-            sources.each { |src| parts << read_source(profile&.id, src.to_s) }
-          end
+          Array(profile&.prompt_files).each { |src| parts << read_source(profile&.id, src.to_s) }
           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.
+          # empty identity here is fatal (`call` raises), not silently patched
+          # with the engine's own boilerplate.
           return identity if identity.empty? || !tool_persistence?(profile)
 
           "#{identity}\n\n#{TOOL_PERSISTENCE}"