insika 0.0.1 → 0.2.0

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

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Reads the Session Store. The ONLY history provider: the three transcript
+      # sources converge here — the Executor does not pick a source. Produces
+      # :history fragments (1 per message), with priority scaled by recency
+      # with a CEILING of 79: the budget cut discards the oldest ones first
+      # and history NEVER outranks skills (80) or identity (100).
+      class Session < ContextProvider
+        def initialize(session_store:)
+          @session_store = session_store
+        end
+
+        def call(request)
+          messages = transcript_for(request)
+          return [] if messages.nil? || messages.empty?
+
+          # 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
+          # (which providers reject), without touching apply_budget itself.
+          eviction_units(messages).each_with_index.map do |unit, idx|
+            ContextFragment.build(
+              # single message stays a Hash (compat with existing fragments); a
+              # multi-message cycle is an Array (seed_history flattens it back).
+              content: unit.size == 1 ? unit.first : unit,
+              placement: :history,
+              # HISTORY_MAX ceiling; idx 0 = oldest (drops first in the cut)
+              priority: [Context::Priority::HISTORY_BASE + idx, Context::Priority::HISTORY_MAX].min,
+              source: id
+            )
+          end
+        end
+
+        private
+
+        # Groups a flat message list into eviction units. An assistant message
+        # carrying tool_calls absorbs the `role: tool` messages that immediately
+        # follow it (its results). Everything else is a unit of one.
+        def eviction_units(messages)
+          normalized = messages.map { |m| normalize(m) }
+          units = []
+          i = 0
+          while i < normalized.length
+            msg = normalized[i]
+            i += 1
+            if msg[:role].to_s == "assistant" && tool_calls?(msg)
+              cycle = [msg]
+              while i < normalized.length && normalized[i][:role].to_s == "tool"
+                cycle << normalized[i]
+                i += 1
+              end
+              units << cycle
+            else
+              units << [msg]
+            end
+          end
+          units
+        end
+
+        # Symbol-keyed message preserving tool_calls / tool_call_id when present
+        # (a plain message keeps just {role, content} — parity with the old shape).
+        def normalize(msg)
+          h = { role: msg[:role] || msg["role"], content: msg[:content] || msg["content"] }
+          tool_calls = msg[:tool_calls] || msg["tool_calls"]
+          tool_call_id = msg[:tool_call_id] || msg["tool_call_id"]
+          h[:tool_calls] = tool_calls if tool_calls
+          h[:tool_call_id] = tool_call_id if tool_call_id
+          h
+        end
+
+                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.
+        def transcript_for(request)
+          return request.checkpoint.messages if request.checkpoint
+
+          explicit = explicit_history(request)
+          return explicit if explicit
+          return session_messages(request.session) if request.session
+
+          nil
+        end
+
+        # Source 2 (explicit history): the handler passes it in request.vars[:history].
+        # Isolated in a single method to change the convention with 1 line.
+        def explicit_history(request)
+          vars = request.vars.to_h
+          vars[:history] || vars["history"]
+        end
+
+        # CONDITIONAL requiredness: when a session is requested, a read
+        # failure becomes a ContextError (aborts the turn); the base required?
+        # does not receive the request, so the behavior lives here.
+        def session_messages(session)
+          @session_store.find(session.id)&.messages || []
+        rescue StandardError => e # read failure (exception/StoreError)
+          raise ContextError.new("Session provider failed with a requested session: #{e.message}",
+                                 provider: id)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Level 1 (progressive disclosure) of the profile's CANDIDATE skills.
+      # The Executor's LoadSkill does NOT come from here: it is built with
+      # resolution.allowed_skills (a policy decision). Context->Policy order: the
+      # provider produces the candidate; the policy cuts afterwards.
+      class Skill < CatalogProvider
+        # priority 80: above deferred tools (70), below pinned identity.
+        def priority = Context::Priority::SKILL
+
+        private
+
+        # 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
+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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Insika
+  module Context
+    module Providers
+      # Level 1 (progressive disclosure) of the profile's deferred TOOLS. The
+      # slice is `profile.tools_deferred`, known at stage 2 — it may be slightly
+      # over-inclusive (showing a deferred tool the Policy later denies); acceptable,
+      # the real cut happens at PROMOTION (tool_search, `deferred ∩ allowed`).
+      class ToolSearch < CatalogProvider
+        # priority 70: below skills (80) in the sacrifice order.
+        def priority = Context::Priority::TOOL_SEARCH
+
+        private
+
+        def entries(request) = @catalog.subset(request.profile.tools_deferred)
+      end
+    end
+  end
+end

data/lib/insika/context_trace_store.rb

@@ -0,0 +1,92 @@
+# 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.
+    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))
+    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"]) }
+          # 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"]) }
+      }
+    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)
+  end
+end

data/lib/insika/delegation_store.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # 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
+  # spliced mid-turn — preserves role alternation + prompt cache). This record is
+  # what survives a kill -9 so a completed child's result is never lost.
+  #
+  # Lifecycle (never backwards): dispatched -> completed -> delivered.
+  #   dispatched  the child was spawned; result not captured yet.
+  #   completed   the child is terminal; result/error captured durably.
+  #   delivered   the result was handed to the parent session (claimed — the
+  #               claim is what makes delivery AT-MOST-ONCE across crashes).
+  #
+  # Normalizes symbol->string on WRITE (the backend only round-trips JSON types),
+  # like the other domain stores.
+  class DelegationStore
+    include Coercion
+
+    SCOPE = "delegations"
+    KEY_PREFIX = "delegation:"
+
+    STATUSES = %i[dispatched completed delivered].freeze
+
+    Delegation = Data.define(
+      :id, :parent_task_id, :parent_session_id, :parent_agent,
+      :child_agent, :child_task_id, :child_session_id, :depth,
+      :status, :result, :error, :created_at, :updated_at
+    )
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> Delegation (:dispatched).
+    def create(parent_task_id:, parent_session_id:, parent_agent:, child_agent:,
+               child_task_id:, child_session_id:, depth:, id: SecureRandom.uuid)
+      record = {
+        "id" => id.to_s,
+        "parent_task_id" => parent_task_id.to_s,
+        "parent_session_id" => parent_session_id&.to_s,
+        "parent_agent" => parent_agent.to_s,
+        "child_agent" => child_agent.to_s,
+        "child_task_id" => child_task_id.to_s,
+        "child_session_id" => child_session_id.to_s,
+        "depth" => depth,
+        "status" => "dispatched",
+        "result" => nil,
+        "error" => nil,
+        "created_at" => timestamp,
+        "updated_at" => timestamp
+      }
+      @store.set(SCOPE, key_for(id), record)
+      to_delegation(record)
+    end
+
+    # -> Delegation | nil
+    def find(id)
+      record = @store.get(SCOPE, key_for(id))
+      record && to_delegation(record)
+    end
+
+    # -> Delegation | nil for a given child task (the terminal hook's lookup). O(n)
+    # scan — single-node, like PendingActionStore#open_for.
+    def find_by_child_task(child_task_id)
+      id = child_task_id.to_s
+      scan { |d| return d if d.child_task_id == id }
+      nil
+    end
+
+    # -> [Delegation] that are NOT delivered yet (boot recovery). completed-but-
+    # undelivered = a crash between capture and delivery; dispatched = the child
+    # may or may not be terminal (the caller checks the child task).
+    def undelivered
+      scan.reject { |d| d.status == :delivered }
+    end
+
+    # dispatched -> completed, capturing the child's result/error. Idempotent: a
+    # second call on an already-completed/delivered record is a no-op (returns the
+    # current record) — the terminal hook and recovery can race.
+    def mark_completed(id, result: nil, error: nil)
+      record = fetch!(id)
+      return to_delegation(record) unless record["status"] == "dispatched"
+
+      record["status"] = "completed"
+      record["result"] = result
+      record["error"] = error
+      touch(id, record)
+    end
+
+    # completed -> delivered, ATOMICALLY (the claim) — across processes, not just
+    # fibers: the read-check-write rides Store#transaction, so two workers racing
+    # the same record serialize on the backend's lock and only one sees
+    # :completed. Returns true only for the caller that won the transition — that
+    # caller (and only it) spawns the delivery turn, so delivery is at-most-once
+    # even if the hook and recovery both fire. A record not in :completed
+    # (already delivered, or still dispatched) -> false.
+    def claim_delivery(id)
+      @store.transaction do
+        record = @store.get(SCOPE, key_for(id))
+        next false unless record && record["status"] == "completed"
+
+        record["status"] = "delivered"
+        record["updated_at"] = timestamp
+        @store.set(SCOPE, key_for(id), record)
+        true
+      end
+    end
+
+    private
+
+    def scan
+      return enum_for(:scan) unless block_given?
+
+      @store.list(SCOPE, KEY_PREFIX).each do |key|
+        record = @store.get(SCOPE, key)
+        yield to_delegation(record) if record
+      end
+    end
+
+    def fetch!(id)
+      @store.get(SCOPE, key_for(id)) ||
+        (raise Insika::NotFoundError, "delegation not found: #{id}")
+    end
+
+    def touch(id, record)
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_delegation(record)
+    end
+
+    def key_for(id) = "#{KEY_PREFIX}#{id}"
+
+    def to_delegation(record)
+      Delegation.new(
+        id: record["id"], parent_task_id: record["parent_task_id"],
+        parent_session_id: record["parent_session_id"], parent_agent: record["parent_agent"],
+        child_agent: record["child_agent"], child_task_id: record["child_task_id"],
+        child_session_id: record["child_session_id"], depth: record["depth"],
+        status: record["status"].to_sym, result: record["result"], error: record["error"],
+        created_at: record["created_at"], updated_at: record["updated_at"]
+      )
+    end
+
+    def timestamp = Time.now.utc.iso8601
+  end
+end