insika 0.8.0 → 1.0.1

data/lib/insika/agent_defaults.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Insika
+  # Platform defaults for agent fields (Settings["agent_defaults"]): an agent
+  # with no value of its own for an INHERITABLE field runs with the platform's.
+  # The agent's own value always wins, whole (no merge of the two).
+  #
+  # Applied only where turns read profiles (the graph, through ProfileSource
+  # below). Authoring (Studio, pack import) reads the agent's own record, so
+  # saving an agent never copies a default into it and it keeps inheriting.
+  #
+  # FIELDS are the ones where "absent" already means "not configured". Fields
+  # where absent means something else (tools_allow nil = every tool) or where
+  # absent and off read the same (the memory/fencing booleans) are left out.
+  module AgentDefaults
+    FIELDS = %w[reliability knowledge memory_retrieval budget alerts guardrails
+                grounding followup distill harvest].freeze
+
+    module_function
+
+    # -> the profile, rebuilt with the defaults it lacks (the same object when
+    # there is nothing to fill).
+    def apply(profile, defaults)
+      fill = FIELDS.each_with_object({}) do |field, acc|
+        value = defaults[field]
+        acc[field.to_sym] = value if !value.nil? && profile.public_send(field).nil?
+      end
+      return profile if fill.empty?
+
+      AgentProfile.build(**profile.to_h.merge(fill))
+    end
+
+    # Like #apply, but a default the agent cannot be built with (saved before it
+    # was validated, or a rerank model the registry dropped since) leaves the
+    # agent on its own values: one bad default must not stop every turn.
+    def apply_safely(profile, defaults)
+      apply(profile, defaults)
+    rescue Insika::ValidationError => e
+      warn "[insika] agent defaults not applied to #{profile.id}: #{e.message}"
+      profile
+    end
+
+    # Raises ValidationError unless an agent can be built with these defaults.
+    def validate!(defaults)
+      fields = defaults.to_h { |field, value| [field.to_sym, value] }
+      AgentProfile.build(id: "agent-defaults", model: nil, **fields)
+      defaults
+    end
+
+    # The source as turns read it (defaults + kits applied), for turn-time readers
+    # wired outside the graph (workflow triggers, persona evals). No settings store
+    # = nothing to apply, the source as is.
+    def for_turns(source, settings_store)
+      return source if settings_store.nil?
+
+      ProfileSource.new(Insika::ProfileSource.coerce(source), settings_store: settings_store)
+    end
+
+    # The agent's own records behind a profile source: what authoring reads and
+    # writes. A plain source is its own.
+    def own(source) = source.is_a?(ProfileSource) ? source.source : source
+
+    # A ProfileSource that hands out profiles with the platform defaults and the
+    # agent's kits (Insika::Kits) applied.
+    # Read-only: writing a profile read here would save the defaults into the
+    # agent, so put/delete refuse; writers use #source (AgentDefaults.own).
+    # Other reads (all_raw) go to the wrapped source untouched.
+    class ProfileSource
+      include Insika::ProfileSource
+
+      attr_reader :source
+
+      def initialize(source, settings_store:)
+        @source = source
+        @settings_store = settings_store
+      end
+
+      def fetch(id)
+        profile = @source.fetch(id)
+        profile && Insika::Kits.apply(fill(profile, normalized), kits)
+      end
+
+      def all
+        values = normalized
+        by_name = kits
+        @source.all.map { |profile| Insika::Kits.apply(fill(profile, values), by_name) }
+      end
+
+      def ids = @source.ids
+
+      def put(*) = raise(Insika::Error, "agent profiles are written through their own source (AgentDefaults.own)")
+      def delete(*) = put
+
+      def respond_to_missing?(name, include_private = false) = @source.respond_to?(name, include_private) || super
+
+      def method_missing(name, ...)
+        return super unless @source.respond_to?(name)
+
+        @source.public_send(name, ...)
+      end
+
+      private
+
+      # Settings["kits"] — applied after the defaults (Insika::Kits).
+      def kits = @settings_store.get["kits"] || {}
+
+      # Every inheritable field is normalized on its own by AgentProfile.build,
+      # so a profile takes the normalized values as they are (Data#with) and is
+      # not rebuilt per read.
+      def fill(profile, values)
+        missing = values.select { |field, _| profile.public_send(field).nil? }
+        missing.empty? ? profile : profile.with(**missing)
+      end
+
+      # The defaults as AgentProfile.build normalizes them, rebuilt only when the
+      # stored defaults change. Frozen: every profile shares them. A field that
+      # does not build is left out (warned once per change), so one bad default
+      # cannot stop every turn.
+      def normalized
+        raw = @settings_store.get["agent_defaults"] || {}
+        digest = raw.hash
+        return @normalized if digest == @normalized_digest
+
+        @normalized = build_values(raw.slice(*FIELDS).compact)
+        @normalized_digest = digest
+        @normalized
+      end
+
+      def build_values(raw)
+        raw.filter_map do |field, value|
+          built = AgentProfile.build(id: "agent-defaults", model: nil, field.to_sym => value)
+          [field.to_sym, Ractor.make_shareable(built.public_send(field))]
+        rescue Insika::ValidationError => e
+          warn "[insika] agent defaults: #{field} not applied: #{e.message}"
+          nil
+        end.to_h
+      end
+    end
+  end
+end

data/lib/insika/agent_file_store.rb

@@ -31,6 +31,13 @@ module Insika
       entry(agent_id, filename.to_s)&.fetch("content", nil)
     end
 
+    # -> { name => content } every file of the agent, from ONE read of its record
+    # (which also carries the version history). Callers that need several files
+    # use this instead of `read` per file.
+    def contents(agent_id)
+      files(agent_id).transform_values { |entry| entry["content"] }
+    end
+
     # -> [String] the agent's file names, lexicographic order.
     def list(agent_id)
       files(agent_id).keys.sort
@@ -88,6 +95,11 @@ module Insika
       entry(agent_id, filename.to_s)&.fetch("history", []) || []
     end
 
+    # -> String | nil: when the current content was written (iso8601).
+    def updated_at(agent_id, filename)
+      entry(agent_id, filename.to_s)&.fetch("updated_at", nil)
+    end
+
     # Restores version `index` from history as the current content (a new write:
     # the current one goes to the top of history). -> Hash (entry) | raises if index
     # invalid / file nonexistent.

data/lib/insika/agent_profile.rb

@@ -35,12 +35,17 @@ module Insika
     #                                   a per-skill flag forced one decision onto every
     #                                   allowlist holding the skill. NOT `Allowlist`
     #                                   semantics — nil means NONE here (SkillCatalog#eager_for).
+    :kits,                            # kit names (Insika::Kits): bundles of skills/tools applied
+    #                                   at READ time by AgentDefaults::ProfileSource — never
+    #                                   copied into the record. Always a [String] ([] = none).
     :context_providers,               # provider allowlist
     :workflows_allow,                 # applied by WorkflowAllowlist
     :policies,                        # names in the Policy Registry
     :prompt_refs,                     # names in the Prompt Catalog
     :limits,                          # timeouts/budgets
     :approvals_required,              # tools that require approval (ApprovalRequired)
+    :customer_confirm,                # tools the CUSTOMER confirms on the next message: the
+    #                                   call is held, the turn ends with a question (nil = none)
     :capabilities,                    # intents the agent can trigger.
     #                                   nil = NONE (opt-in, see above).
     :subagents,                       # allowlist of child agent ids this agent MAY spawn
@@ -51,19 +56,23 @@ module Insika
     :tools_deferred,                  # searchable-not-wired tools (Tool Search).
     #                                   nil = no deferred (all eager — parity);
     #                                   [names] ⊆ allowed_tools, exposed via tool_search.
+    :shared_conversations,            # opt-in authoritative conversation persistence
     :memory,                          # cross-session memory.
     #                                   nil/false = OFF (parity: provider []; the `remember`
     #                                   tool not wired); true = ON. Same opt-in as capabilities.
+    :memory_retrieval,                # optional reranked context selection; nil = legacy memory block.
     :prompt_caching,                  # Anthropic prompt caching (R3): nil/false = OFF
     #                                   (parity); true = ON. Same opt-in as `memory`. When ON
     #                                   AND the resolved provider is Anthropic, ChatBuilder sets
-    #                                   ONE cache breakpoint at the end of the system block
-    #                                   (caches tools+system by the tools->system->messages
-    #                                   prefix order; immune to history eviction). PRE-AUDIT:
-    #                                   the system prompt MUST be byte-stable between turns —
-    #                                   a context provider injecting volatile content into
-    #                                   :system turns every turn into a paid cache WRITE with
-    #                                   no read hit. Enable only for stable-system agents.
+    #                                   the cache breakpoint at the end of the IDENTITY layer
+    #                                   of the system (prompt, skills, tool index); memory,
+    #                                   knowledge and briefing render below it as a second
+    #                                   block, so a per-turn change there never re-writes the
+    #                                   cached prefix. Immune to history eviction too
+    #                                   (tools->system->messages prefix order). What still
+    #                                   costs a WRITE every turn: a provider declaring
+    #                                   `layer :identity` while emitting per-turn bytes —
+    #                                   the doctor's cache-layers check flags it.
     :tool_persistence,                # the engine's "Tool discipline" block in the system
     #                                   prompt (retry weak/empty tool results with a different
     #                                   approach before giving up). THE ONE OPT-OUT FIELD:
@@ -81,9 +90,22 @@ module Insika
     #                                   THE MODEL SEES: an older full result is only the first
     #                                   occurrence; a model that wants an older detail re-calls
     #                                   the tool. Cheap half of compaction for bloated histories.
+    :fencing,                         # third-party text is sanitized before the model reads
+    #                                   it: nil/false = OFF (parity — bytes reach the model
+    #                                   as-is); true = ON. Same opt-in as `memory`. When ON,
+    #                                   every tool result (after the evidence reshape), every
+    #                                   <memory> fact/note and every <knowledge> concept pass
+    #                                   Insika::Fence (NFKC, invisible/control characters out,
+    #                                   transcript- and tool-call-shaped tags removed, forged
+    #                                   turn markers defused, per-leaf cap), and the FenceNotice
+    #                                   sentence rides under the identity. Default OFF this
+    #                                   release: the goldens were baselined on unfenced bytes.
     :params,                          # LLM generation params: a Hash with
     #                                   temperature/max_tokens/thinking, applied to the chat at
-    #                                   stage 5. {} = provider defaults (parity).
+    #                                   stage 5. {} = provider defaults (parity). Plus
+    #                                   `provider_routing` — which UPSTREAM serves the model, for
+    #                                   a gateway that has several; emitted under the wire key
+    #                                   `provider` (OpenRouter's shape).
     :budget,                          # spend caps per (tenant, agent) over
     #                                   CALENDAR windows (WS2): { "daily" => int,
     #                                   "monthly" => int, "soft" => bool, "alert_at" => 0.8 }.
@@ -318,11 +340,12 @@ module Insika
     # platform `default_model` (Settings) at turn start via the ModelResolver.
     def self.build(id:, model: nil, provider: nil, base_prompt: "", prompt_files: [],
                    tools_allow: nil, tools_deny: [], tools_allow_groups: nil, skills: nil,
-                   skills_eager: nil, context_providers: nil, workflows_allow: nil,
+                   skills_eager: nil, kits: nil, context_providers: nil, workflows_allow: nil,
                    policies: [], prompt_refs: [], limits: {}, approvals_required: nil,
-                   capabilities: nil, subagents: nil, tools_deferred: nil, memory: nil,
+                   customer_confirm: nil,
+                   capabilities: nil, subagents: nil, tools_deferred: nil, memory: nil, memory_retrieval: nil, shared_conversations: false,
                    prompt_caching: nil, tool_persistence: nil, tool_output_compression: nil,
-                    params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
+                   fencing: nil, params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
                     refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {},
                      budget: nil, reliability: nil, alerts: nil, routes: nil, stuck_signal: nil,
 outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil,
@@ -332,18 +355,21 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
         prompt_files: Array(prompt_files), tools_allow: tools_allow,
         tools_deny: Array(tools_deny), tools_allow_groups: tools_allow_groups, skills: skills,
         skills_eager: skills_eager,
+        kits: Array(kits).map(&:to_s).uniq,
         context_providers: context_providers, workflows_allow: workflows_allow,
         policies: normalize_policies(policies, tools_allow: tools_allow, tools_deny: tools_deny,
                                      tools_allow_groups: tools_allow_groups),
         prompt_refs: Array(prompt_refs),
         limits: DEFAULT_LIMITS.merge(limits), approvals_required: approvals_required,
+        customer_confirm: normalize_customer_confirm(customer_confirm, approvals_required),
         capabilities: capabilities,
         # opt-in like capabilities: nil => NONE. Array-normalize a present value so
         # readers get a clean [] and the ChatBuilder gate (present? => wire) is stable.
         subagents: subagents.nil? ? nil : Array(subagents).map(&:to_s),
-        tools_deferred: tools_deferred, memory: memory,
+        tools_deferred: tools_deferred, memory: memory, shared_conversations: shared_conversations == true,
+        memory_retrieval: normalize_memory_retrieval(memory_retrieval),
         prompt_caching: prompt_caching, tool_persistence: tool_persistence,
-        tool_output_compression: tool_output_compression,
+        tool_output_compression: tool_output_compression, fencing: fencing,
         # The free-form hashes arrive with symbol keys (internal build) OR string
         # keys (StoredProfileSource JSON round-trip). Normalize to string keys ONCE
         # here — the single front door every profile passes through — so no reader
@@ -390,10 +416,9 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
         # free-form hashes; shape-validated by the command/engine/doctor
         # (never here — the refinement precedent). nil = off (parity).
         harvest: Coercion.deep_stringify(harvest),
-        # knowledge is profile DATA, deep-stringified like the other
-        # free-form hashes; shape-validated by the extractor/doctor
-        # (never here — the refinement precedent). nil = off (parity).
-        knowledge: Coercion.deep_stringify(knowledge),
+        # knowledge is profile DATA. Legacy extraction remains free-form;
+        # an explicit rerank declaration is validated when loaded.
+        knowledge: normalize_knowledge(knowledge),
         # schedules is profile DATA, deep-stringified like the other
         # free-form hashes (an ARRAY of declarations); parsed into
         # Insika::Schedule entries by the engine/doctor/Studio (shape-validated
@@ -402,6 +427,46 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
       )
     end
 
+    def self.normalize_knowledge(value)
+      config = Coercion.deep_stringify(value)
+      return config unless config.is_a?(Hash) && config.key?("rerank")
+
+      validate_rerank(config, "knowledge")
+      config
+    end
+
+    def self.normalize_memory_retrieval(value)
+      return nil if value.nil?
+
+      config = Coercion.deep_stringify(value)
+      raise ValidationError, "memory_retrieval must be an object" unless config.is_a?(Hash)
+
+      validate_rerank(config, "memory_retrieval", require_top_k: true)
+      config
+    end
+
+    def self.validate_rerank(config, field, require_top_k: false)
+      rerank = config["rerank"]
+      raise ValidationError, "#{field}.rerank must be an object" unless rerank.is_a?(Hash)
+
+      top_k = require_top_k ? config["top_k"] : config.fetch("top_k", 5)
+      limit = rerank["candidate_limit"]
+      timeout = rerank["timeout_seconds"]
+      valid = top_k.is_a?(Integer) && top_k.positive? &&
+              limit.is_a?(Integer) && limit >= top_k && limit <= 100 &&
+              timeout.is_a?(Numeric) && timeout.finite? && timeout.positive? &&
+              %w[provider model].all? { |key| rerank[key].is_a?(String) && !rerank[key].strip.empty? }
+      raise ValidationError, "invalid #{field}.rerank configuration" unless valid
+
+      require "ruby_llm"
+      begin
+        model = RubyLLM.models.find(rerank["model"], provider: rerank["provider"])
+      rescue RubyLLM::ModelNotFoundError
+        raise ValidationError, "#{field}.rerank model is not registered for provider"
+      end
+      raise ValidationError, "#{field}.rerank model does not support reranking" unless model.type == :rerank
+    end
+
     # Declaring a tool allow/deny list IS opting into it. The list is only ever
     # applied by the builtin `tool_allowlist` policy, and the Policy::Engine runs
     # ONLY the policies a profile names — so a profile with `tools_allow: [a, b]`
@@ -449,6 +514,23 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
       names
     end
 
+    # nil/empty -> nil (off); else [String], trimmed, uniq. A tool is confirmed by
+    # the customer OR approved by the operator, never both: the two hold a call in
+    # opposite ways (the turn ends with a question vs. the turn suspends), and one
+    # tool cannot do both at once.
+    def self.normalize_customer_confirm(list, approvals)
+      names = Array(list).map { |n| n.to_s.strip }.reject(&:empty?).uniq
+      return nil if names.empty?
+
+      both = names & Array(approvals).map(&:to_s)
+      unless both.empty?
+        raise Insika::ValidationError,
+              "customer_confirm and approvals_required overlap (#{both.join(', ')}): a tool is " \
+              "confirmed by the customer or approved by the operator, not both"
+      end
+      names
+    end
+
     # opt-in for an optional tool = being in the agent's allow list.
     def tool_opted_in?(name)
       Array(tools_allow).include?(name)

data/lib/insika/artifact_signing.rb

@@ -22,6 +22,17 @@ module Insika
     AUTHENTICATED_PATH = "/studio/artifacts/%{id}/content"
     SIGNED_PATH = "/studio/artifacts/s/%{id}?exp=%{exp}&sig=%{sig}"
 
+    # The Studio's signing config, read from the environment.
+    # -> { key:, ttl:, base_url: } | nil (no signing key -> no signed surface).
+    def studio_config
+      key = Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_KEY")
+      return nil if key.to_s.empty?
+
+      { key: key,
+        ttl: (Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_TTL") || 604_800).to_i,
+        base_url: Insika::Coercion.presence(Insika::EnvSchema.read("INSIKA_PUBLIC_URL")).to_s }
+    end
+
     # -> hex token (64 chars) | nil when the key is blank (no signed surface).
     def sign(id:, expires_at:, key:)
       key = key.to_s

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

@@ -158,6 +158,11 @@
             log.scrollTop = log.scrollHeight;
           } else if (event === "working" && !bubbleEl && !note) {
             note = say("note", "working…");
+          } else if (event === "ui" && data.items && data.items.length) {
+            // A presentation tool picked cards: a plain list of caption + link.
+            // The host page restyles or replaces this; the protocol is the frame.
+            if (note) { note.remove(); note = null; }
+            show(data);
           } else if (event === "error") {
             if (note) { note.remove(); note = null; }
             throw new Error(data.message || "something went wrong");
@@ -257,6 +262,34 @@
 
   // --- helpers --------------------------------------------------------
 
+  function show(ui) {
+    var list = el("ul", "insika-m ui");
+    if (ui.title) {
+      var head = el("li", "title");
+      head.textContent = ui.title;
+      list.appendChild(head);
+    }
+    ui.items.forEach(function (item) {
+      var li = el("li", "");
+      var label = item.caption || item.id || item.url;
+      // Only http(s) becomes a link: the url is backend data, and a
+      // `javascript:` or `data:` scheme must never be one click away.
+      if (/^https?:\/\//i.test(item.url || "")) {
+        var a = el("a", "");
+        a.href = item.url;
+        a.target = "_blank";
+        a.rel = "noopener";
+        a.textContent = label;
+        li.appendChild(a);
+      } else {
+        li.textContent = label;
+      }
+      list.appendChild(li);
+    });
+    log.appendChild(list);
+    log.scrollTop = log.scrollHeight;
+  }
+
   function say(kind, content) {
     var node = el("div", "insika-m " + kind);
     node.textContent = content;

data/lib/insika/channels/web.rb

@@ -155,8 +155,9 @@ module Insika
       # path — `POST /messages` with an unknown id is a 404, not a new conversation.
       def mint_session_id = "#{@id}:#{SecureRandom.hex(16)}"
 
-      # Turn Event -> SSE frame | nil. Four frames, which is the whole widget
-      # protocol: what to type, what to say while a tool runs, and how it ended.
+      # Turn Event -> SSE frame | nil. Five frames, which is the whole widget
+      # protocol: what to type, what to say while a tool runs, what to show
+      # (a presentation tool's cards), and how it ended.
       #
       # `:intermediate` and `:thinking` are deliberately absent. `:content` is the
       # ANSWER — the model's narration on the way there is internal, and a
@@ -165,6 +166,8 @@ module Insika
         case event.type
         when :content        then sse("delta", { delta: event.data[:delta].to_s })
         when :tool_call      then sse("working", { name: event.data[:name].to_s })
+        when :ui             then sse("ui", { component: event.data[:component].to_s, title: event.data[:title],
+                                              items: Array(event.data[:items]) })
         when :task_completed then sse("done", {})
         when :task_failed    then sse("error", { message: event.data[:message].to_s })
         when :task_cancelled then sse("error", { message: "task cancelled" })