insika 0.9.0 → 1.0.1

data/lib/insika/server/responses.rb

@@ -42,9 +42,23 @@ module Insika
         message = extract_input(body[:input])
 
         out = { agent: agent.strip, user: user, message: message }
+        if body.key?(:shared_conversation)
+          raise Insika::ValidationError, 'shared_conversation must be an object and user_text a string' unless body[:shared_conversation].is_a?(Hash) && body[:user_text].is_a?(String)
+          out[:shared_conversation] = body[:shared_conversation]
+          out[:user_text] = body[:user_text]
+        end
         (origin = Insika::MessageOrigin.parse!(body[:origin])) && (out[:origin] = origin)
+        # the caller's text that rides ahead of `input` to the model; guardrails read `input` alone
+        unless body[:context].nil? || body[:context].is_a?(String)
+          raise Insika::ValidationError, "context must be a string"
+        end
+        out[:context] = body[:context] if body[:context]
         # WS8: the optional customer_key — per-customer memory scope + purge handle
         (customer = Insika::Coercion.presence(body[:customer])) && (out[:customer] = customer)
+        # the optional labels the Studio shows and searches the conversation by
+        Insika::SessionStore::CUSTOMER_LABELS.each do |key|
+          out[key.to_sym] = body[key.to_sym] if body[key.to_sym].is_a?(String)
+        end
         # WS9: the multimodal OPENAI shape — `input` as an array of content parts
         # ({type: text/image/audio}) is preserved additively alongside the
         # joined text; a string input stays byte-identical to before. The
@@ -197,7 +211,11 @@ module Insika
           # `model` travels alongside usage in the event; in the OpenAI shape it is a sibling of
           # usage (pure tokens in usage).
           model = usage[:model] || usage["model"]
-          response[:usage] = usage.reject { |k, _| k.to_s == "model" }
+          projected = usage.transform_keys(&:to_sym).reject { |k, _| k == :model }
+          cache = projected[:cached_tokens].to_i + projected[:cache_creation_tokens].to_i
+          projected[:input_tokens] += cache if projected[:input_tokens]
+          projected[:total_tokens] += cache if projected[:total_tokens]
+          response[:usage] = projected
           response[:model] = model if model
         end
         # Opt-in per-turn latency breakdown (INSIKA_TURN_TIMING). Absent

data/lib/insika/session_actor.rb

@@ -23,28 +23,47 @@ module Insika
   # would duplicate the invariant; putting it in the Executor would mix turn
   # execution with queue policy.
   class SessionActor
-    def initialize(session_id:, executor:, parent: Async::Task.current)
+    # `on_idle` is called with the actor once its queue drains and the loop ends, so
+    # the owner can drop it: an idle session holds no fiber.
+    def initialize(session_id:, executor:, parent: Async::Task.current, on_idle: nil)
       @session_id = session_id
       @executor = executor
+      @on_idle = on_idle
       @queue = Async::Queue.new
       @running = false
-      # The turn currently sitting at the door: created and :queued, but not yet
-      # released to run. `collect` merges into THIS one. nil whenever there is
-      # nothing mergeable — which is the common case and the safe default.
-      @pending = nil
+      # The turns sitting at the door: created and :queued, but not yet released to
+      # run — whether waiting out a debounce window or simply queued behind the turn
+      # in flight. `collect` merges into the LAST one (the turn that has not
+      # answered yet; appending to an older one would put a newer fragment in an
+      # older message). Keyed by task so a turn released from the FIFO still finds
+      # its OWN count — with a single slot, a second turn enqueued behind the first
+      # would take the first's fragments with it. Empty is the common case and the
+      # safe default: a policy that does not merge never opens one.
+      @doors = {}
       @loop = parent.async { |t| t.annotate("session:#{session_id}"); run_loop }
     end
 
     # Enqueues a turn (FIFO). Non-blocking: the handler responds with an
     # immediate {task_id:} even if the turn stays :queued behind another. -> task.id.
     #
-    # `policy` (a QueuePolicy) opens the debounce window for this turn; nil or a
-    # policy without a window behaves exactly as before — dequeued and run at once.
+    # `policy` (a QueuePolicy) decides the door: a merging mode (`collect`/`steer`)
+    # opens it here, and a `debounce_ms` on top of that also holds the turn once it
+    # reaches the front. A nil policy or `followup` behaves exactly as before —
+    # nothing to merge into, dequeued and run at once.
     #
     # `timing`  is the channel clock a channel turn allocated at 202
     # acceptance and already stamped `:inbound`; it rides the queue so the debounce
     # window and the FIFO wait land INSIDE first_balloon_ms.
     def enqueue(task, profile:, resume_from: nil, policy: nil, timing: nil)
+      # The door opens HERE, not when the turn is dequeued. "Created and not yet
+      # started" lasts as long as the turn IN FRONT takes, and that whole wait is
+      # mergeable: the turn has not spoken, so a fragment appended to it costs
+      # nothing and saves an answer. Opening the door only for a debounce window
+      # (where it used to live) left every message that arrived while a turn sat in
+      # the FIFO with nothing to join — it became a turn of its own behind two
+      # others, and a `stream=false` caller then waited for BOTH to run before it
+      # heard anything. A window is now what EXTENDS the door, never what creates it.
+      @doors[task.id] = open_door(task) if policy&.collect?
       @queue.enqueue([task, profile, resume_from, policy, timing])
       task.id
     end
@@ -58,7 +77,7 @@ module Insika
     # and neither yields between the check and the write below, so the "is it
     # still mergeable" test and the append cannot interleave.
     def collect(text)
-      pending = @pending
+      pending = @doors.values.last
       return nil if pending.nil?
 
       @executor.task_store.append_message(pending[:task_id], text)
@@ -88,15 +107,15 @@ module Insika
     # request's path.
     attr_reader :current_task
 
-    # Is there a turn at the door that `collect` could still merge into?
-    def collecting? = !@pending.nil?
+    # Is there a turn at the door that `collect` could still merge into? True from
+    # the moment a merging policy enqueues one until it starts running.
+    def collecting? = !@doors.empty?
 
     # Is the loop still alive? (the Executor revalidates before reusing from the
     # cache — a dead loop would black-hole queued turns).
     def alive? = !!@loop&.running?
 
-    # Shuts down the loop (server shutdown / tests — the loop blocks forever on
-    # dequeue when idle).
+    # Shuts down the loop (server shutdown / tests).
     def stop = @loop&.stop
 
     private
@@ -118,45 +137,56 @@ module Insika
           @running = false
           @current_task = nil
         end
+        # Ends with the last queued turn. A parked fiber per session ever seen grew a
+        # worker without bound; the next message starts a fresh actor. No yield sits
+        # between this check and the loop's end, so an enqueue cannot slip in.
+        break if @queue.empty?
       end
+      @on_idle&.call(self)
+      nil # the finished task must not hold the actor (see TaskActor#run)
     end
 
-    # the debounce window. Sleeps on the LOOP's fiber, never on the
-    # request's, so the POST is acked immediately and the platform does not retry.
-    # Returns the task to run (re-read from the store when fragments merged into it,
-    # since the in-memory Task is a frozen snapshot of an older message).
+    # Closes the turn's door and reports what it caught. The debounce
+    # window (when the policy has one) is the EXTRA wait held here, on the LOOP's
+    # fiber and never on the request's, so the POST is acked immediately and the
+    # platform does not retry. Returns the task to run — re-read from the store when
+    # fragments merged into it, since the in-memory Task is a frozen snapshot of an
+    # older message.
     def hold_at_the_door(task, policy)
-      return task unless policy&.debounce?
+      pending = @doors[task.id]
+      return task if pending.nil?
 
-      @pending = { task_id: task.id, count: 1, version: 0, arrivals: [Time.now.utc.iso8601] }
       begin
-        wait_for_quiet(policy)
-        merged = @pending[:count]
-        arrivals = @pending[:arrivals]
+        wait_for_quiet(policy, pending) if policy&.debounce?
+        merged = pending[:count]
       ensure
-        # The window is closed BEFORE the turn runs, under every exit path: a
-        # `collect` that slipped in here would append to a task about to be read.
-        @pending = nil
+        # The door closes BEFORE the turn runs, under every exit path: a `collect`
+        # that slipped in here would append to a task about to be read.
+        @doors.delete(task.id)
       end
 
       return task if merged == 1
 
-      @executor.emit_coalesced(task, merged: merged, arrivals: arrivals)
+      @executor.emit_coalesced(task, merged: merged, arrivals: pending[:arrivals])
       @executor.task_store.find(task.id) || task
     end
 
+    def open_door(task)
+      { task_id: task.id, count: 1, version: 0, arrivals: [Time.now.utc.iso8601] }
+    end
+
     # Sleeps in `debounce_ms` slices, restarting whenever a fragment arrives
     # (`version` moved), until either a slice passes in silence or the total
     # deferral reaches `debounce_max_ms` — the ceiling that stops a customer who
     # keeps typing from postponing their own answer forever.
-    def wait_for_quiet(policy)
+    def wait_for_quiet(policy, pending)
       quiet = policy.debounce_ms / 1000.0
       deadline = monotonic + (policy.debounce_max_ms / 1000.0)
 
       loop do
-        mark = @pending[:version]
+        mark = pending[:version]
         Async::Task.current.sleep(quiet)
-        break if @pending[:version] == mark # a full slice of silence
+        break if pending[:version] == mark # a full slice of silence
         break if monotonic >= deadline
       end
     end

data/lib/insika/session_store.rb

@@ -20,7 +20,20 @@ module Insika
     include Coercion
 
     SCOPE = "sessions"
+    STATS_SCOPE = "session_stats" # one small record per session, see #write
+    # Optional Strings a caller sends to label a conversation in the Studio
+    # (shown and searched there; no effect on memory scope).
+    CUSTOMER_LABELS = %w[customer_name customer_phone].freeze
     KEY_PREFIX = "session:"
+    # Simulator (`sim-<chat>`) and eval (`eval-<id>`) sessions are synthetic
+    # traffic: nothing learns from them
+    # (knowledge extraction, harvest). A tenant-scoped id ("<tenant>:sim-…")
+    # is judged by its last segment.
+    SYNTHETIC_PREFIXES = %w[sim- eval-].freeze
+
+    def self.synthetic?(session_id)
+      session_id.to_s.split(":").last.to_s.start_with?(*SYNTHETIC_PREFIXES)
+    end
 
     Session = Data.define(:id, :messages, :vars, :memory_refs,
                           :created_at, :updated_at, :briefing, :evidence, :compaction) do
@@ -56,7 +69,7 @@ module Insika
         "created_at" => now,
         "updated_at" => now
       }
-      @store.set(SCOPE, key, record)
+      write(record)
       to_session(record)
     end
 
@@ -78,13 +91,18 @@ module Insika
     # a non-supervised deployment) would interleave read/set and LOSE messages —
     # there is no compare-and-swap here. Route same-session writes through the
     # SessionActor; see session_actor.rb.
-    def append_messages(id, messages)
+    # `agent:` names the session's agent when it has none yet (a turn with no
+    # customer never stamped one), riding this write instead of one of its own.
+    def append_messages(id, messages, agent: nil)
       record = fetch!(id)
       incoming = (messages.is_a?(Hash) ? [messages] : Array(messages))
                  .map { |msg| stamp(deep_stringify(msg)) }
       record["messages"] += incoming
+      if agent && Coercion.presence((record["vars"] ||= {})["agent"]).nil?
+        record["vars"]["agent"] = agent.to_s
+      end
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
       to_session(record)
     end
 
@@ -94,7 +112,7 @@ module Insika
       record = fetch!(id)
       record["vars"] = record["vars"].merge(deep_stringify(vars))
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
       to_session(record)
     end
 
@@ -111,7 +129,7 @@ module Insika
       # presentation tool joins on in a LATER turn. Absent until a card arrives.
       ev["cards"] = EvidenceLedger.merge_cards(ev["cards"], cards) unless Array(cards).empty?
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
       to_session(record)
     end
 
@@ -138,7 +156,7 @@ module Insika
       value = Coercion.presence(Coercion.utf8(value.to_s))
       value ? briefing["fields"][field.to_s] = value : briefing["fields"].delete(field.to_s)
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
       to_session(record)
     end
 
@@ -149,7 +167,7 @@ module Insika
       briefing = record["briefing"] ||= { "fields" => {}, "next_step" => nil }
       briefing["next_step"] = Coercion.presence(Coercion.utf8(text.to_s))
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
       to_session(record)
     end
 
@@ -164,31 +182,130 @@ module Insika
     # read/mutate/set path suspends, so no other writer can interleave
     # mid-RMW. The LLM call that produced the summary happened BEFORE this
     # method; only the plain write lives here.
-    def set_compaction(id, summary:, upto:, model: nil)
+    def set_compaction(id, summary: nil, upto:, model: nil, native: nil)
       record = fetch!(id)
       current = record["compaction"]
       upto = Integer(upto)
       return to_session(record) if current && upto <= current["upto"].to_i
 
       record["compaction"] = {
-        "summary" => Coercion.utf8(summary.to_s),
+        "summary" => native ? nil : Coercion.utf8(summary.to_s),
+        "native" => native && Coercion.deep_stringify(native),
         "upto" => upto,
         "runs" => (current ? current["runs"].to_i : 0) + 1,
         "model" => Coercion.presence(model.to_s),
         "at" => timestamp
       }.compact
       record["updated_at"] = timestamp
-      @store.set(SCOPE, key_for(id), record)
+      write(record)
+      to_session(record)
+    end
+
+    # -> Session. A person's verdict on one guardrail flag:
+    # messages[message]["guardrail_flags"][flag]["review"] = { status, at }.
+    # status "reported" (a false positive to fix in the corpus) or "resolved";
+    # nil clears it. updated_at is left alone — a review is not conversation
+    # activity. NotFoundError for an unknown session, message or flag.
+    REVIEW_STATUSES = %w[reported resolved].freeze
+
+    def review_guardrail_flag(id, message:, flag:, status:)
+      record = fetch!(id)
+      message = Integer(message)
+      flag = Integer(flag)
+      # a negative index would count from the end: a different flag
+      target = Array(record["messages"])[message] unless message.negative?
+      flags = target.is_a?(Hash) ? Array(target["guardrail_flags"]) : []
+      entry = flags[flag] unless flag.negative?
+      raise Insika::NotFoundError, "guardrail flag not found: #{id} #{message}/#{flag}" unless entry.is_a?(Hash)
+
+      if status.nil?
+        entry.delete("review")
+      else
+        raise Insika::ValidationError, "unknown review status: #{status}" unless REVIEW_STATUSES.include?(status.to_s)
+
+        entry["review"] = { "status" => status.to_s, "at" => timestamp }
+      end
+      write(record, amend: true)
       to_session(record)
     end
 
     # -> bool (delegates to the backend: false for a nonexistent id)
     def delete(id)
+      @store.delete(STATS_SCOPE, key_for(id))
       @store.delete(SCOPE, key_for(id))
     end
 
     # -> enumerates ids without the "session:" prefix. Without a block,
     # returns an Enumerator.
+    # -> [Session] every record, from ONE bulk read of the backend (see
+    # Store#entries) instead of a read per id.
+    def all
+      @store.entries(SCOPE, KEY_PREFIX).map { |_, record| to_session(record) }
+    end
+
+    # -> [Session] the `limit` most recently written sessions, newest first, from
+    # one read (Store#recent) instead of reading every session to sort them.
+    # `offset` skips that many of the newest (the next page).
+    def recent(limit, offset: 0)
+      # offset only when paging: a backend written for the 3-argument #recent keeps working
+      rows = offset.zero? ? @store.recent(SCOPE, KEY_PREFIX, limit) : @store.recent(SCOPE, KEY_PREFIX, limit, offset)
+      rows.map { |_, record| to_session(record) }
+    end
+
+    # -> Integer sessions stored, from the keys alone (no record is read).
+    def count = @store.list(SCOPE, KEY_PREFIX).size
+
+    # What a dashboard needs of a session without its messages: a few bytes per
+    # session, written with it, instead of the whole record (messages included).
+    # last_role: who spoke last ("user" = the customer is waiting); nil on stats
+    # written before it existed, until the session's next write.
+    # flagged: messages carrying a guardrail flag nobody resolved (a resolved
+    # flag stays on the message as history); reported: flags a person
+    # marked as a false positive and nobody resolved yet. Both 0 on stats
+    # written before they existed, until the session's next write.
+    # reported_at: the newest of those reports.
+    Stat = Data.define(:id, :updated_at, :message_count, :vars, :last_role, :flagged, :reported, :reported_at) do
+      def initialize(id:, updated_at:, message_count:, vars:, last_role: nil, flagged: 0, reported: 0, reported_at: nil) = super
+    end
+
+    # -> [Stat] every session's stats, in no particular order: small enough to read
+    # whole, so a reader never depends on the order they were written in.
+    def all_stats
+      @store.entries(STATS_SCOPE, KEY_PREFIX).map { |key, stat| to_stat(key, stat) }
+    end
+
+    # Bumped when stats gain a field (2: flagged/reported; 3: flagged skips
+    # resolved flags), so backfill_stats rewrites the older ones instead of
+    # only filling the missing.
+    STATS_VERSION = 3
+
+    # A guardrail flag still marks its conversation until a person resolves it.
+    def self.open_flag?(flag) = !(flag.is_a?(Hash) && flag.dig("review", "status") == "resolved")
+
+    # Writes the stats of every session that has none or older ones (sessions
+    # stored before a field existed) and deletes stats whose session is gone.
+    # Idempotent and safe with the app running: each batch re-reads inside a
+    # transaction, skipping a session that wrote its own stats meanwhile or was
+    # deleted. -> stats written.
+    def backfill_stats(batch: 500)
+      have = @store.entries(STATS_SCOPE, KEY_PREFIX).filter_map { |key, stat| key if current_stat?(stat) }.to_set
+      written = 0
+      @store.list(SCOPE, KEY_PREFIX).reject { |key| have.include?(key) }.each_slice(batch) do |keys|
+        @store.transaction do
+          keys.each do |key|
+            next if current_stat?(@store.get(STATS_SCOPE, key))
+
+            record = @store.get(SCOPE, key) or next
+            @store.set(STATS_SCOPE, key, stats_of(record))
+            written += 1
+          end
+        end
+      end
+      live = @store.list(SCOPE, KEY_PREFIX).to_set
+      @store.list(STATS_SCOPE, KEY_PREFIX).each { |key| @store.delete(STATS_SCOPE, key) unless live.include?(key) }
+      written
+    end
+
     def each_id
       return enum_for(:each_id) unless block_given?
 
@@ -199,6 +316,38 @@ module Insika
 
     private
 
+    # The one write of a session record: the record and its stats, side by side.
+    # amend: an edit that is not activity keeps the session's place in #recent.
+    def write(record, amend: false)
+      key = key_for(record["id"])
+      amend ? @store.amend(SCOPE, key, record) : @store.set(SCOPE, key, record)
+      @store.set(STATS_SCOPE, key, stats_of(record))
+    end
+
+    def current_stat?(stat) = stat.is_a?(Hash) && stat["v"].to_i >= STATS_VERSION
+
+    def stats_of(record)
+      messages = Array(record["messages"])
+      last = messages.last
+      vars = record["vars"] || {}
+      flags = messages.map { |m| m.is_a?(Hash) ? Array(m["guardrail_flags"]) : [] }
+      flagged = flags.count { |fs| fs.any? { self.class.open_flag?(_1) } }
+      reported = flags.flatten.select { |f| f.is_a?(Hash) && f.dig("review", "status") == "reported" }
+      { "v" => STATS_VERSION, "updated_at" => record["updated_at"], "message_count" => messages.size,
+        "agent" => vars["agent"], "customer" => vars["customer"],
+        "last_role" => last.is_a?(Hash) ? last["role"] : nil, "flagged" => (flagged if flagged.positive?),
+        "reported" => (reported.size if reported.any?), "reported_at" => reported.filter_map { |f| f.dig("review", "at") }.max,
+        **vars.slice(*CUSTOMER_LABELS) }.compact
+    end
+
+    def to_stat(key, stat)
+      Stat.new(id: key.delete_prefix(KEY_PREFIX), updated_at: stat["updated_at"],
+               message_count: stat["message_count"].to_i,
+               vars: stat.slice("agent", "customer", *CUSTOMER_LABELS),
+               last_role: stat["last_role"], flagged: stat["flagged"].to_i, reported: stat["reported"].to_i,
+               reported_at: stat["reported_at"])
+    end
+
     def key_for(id)
       "#{KEY_PREFIX}#{id}"
     end

data/lib/insika/settings_store.rb

@@ -36,7 +36,7 @@ module Insika
       # platform utility_model) into one history fragment. `prompt` replaces
       # the engine default wholesale (the distill convention). enabled: false
       # = parity (nothing runs). Additive keys — reads overlay DEFAULTS.
-      "compaction" => { "enabled" => false, "keep_last" => 20,
+      "compaction" => { "enabled" => false, "mode" => "summary", "keep_last" => 20,
                         "compact_after" => 40, "model" => nil },
       # Fencing (per-agent `fencing` flag): the cap on ONE string leaf of a tool
       # result after sanitizing. Platform-wide — the leaf size is a context-budget
@@ -103,6 +103,23 @@ module Insika
         "agent_token_ceiling" => nil,
         "agent_token_window" => 86_400,
         "limit_response" => nil
+      },
+      # Burst policy — the platform layer of the QueuePolicy (session vars >
+      # agent limits > HERE > QueuePolicy::DEFAULTS). nil = no platform default:
+      # the key falls through to QueuePolicy::DEFAULTS (followup, no window,
+      # steer_max 5, raw text). Same keys the agent config form writes into
+      # profile.limits, so one deploy-wide answer no longer means editing every
+      # agent. Additive key — reads overlay DEFAULTS.
+      # Platform defaults for agent fields (Insika::AgentDefaults): an agent with
+      # no value of its own for one of AgentDefaults::FIELDS runs with this one.
+      # Written through #put_agent_defaults. Additive key.
+      "agent_defaults" => {},
+      "queue" => {
+        "queue_mode" => nil,
+        "debounce_ms" => nil,
+        "debounce_max_ms" => nil,
+        "steer_max_messages" => nil,
+        "steer_join" => nil
       }
     }.freeze
 
@@ -123,6 +140,35 @@ module Insika
       merged
     end
 
+    # Replaces the platform agent defaults per FIELD (AgentDefaults): a sent field
+    # replaces its whole value (unlike #update, which deep-merges and could never
+    # drop a key the form removed); nil drops it; fields not sent stay.
+    # -> Hash (the resulting agent_defaults).
+    def put_agent_defaults(patch)
+      data = get
+      defaults = (data["agent_defaults"] || {}).merge(stringify(patch || {})).compact
+      data["agent_defaults"] = defaults
+      @cs.put(SCOPE, KEY, data)
+      defaults
+    end
+
+    # Kits (Insika::Kits), replaced per kit: a sent kit replaces its whole value,
+    # nil deletes it, other kits stay. -> Hash (all kits).
+    def kits = get["kits"] || {}
+
+    def put_kit(name, kit)
+      data = get
+      all = (data["kits"] || {}).dup
+      if kit.nil?
+        all.delete(name.to_s)
+      else
+        all[name.to_s] = Insika::Kits.validate!(name, kit)
+      end
+      data["kits"] = all
+      @cs.put(SCOPE, KEY, data)
+      all
+    end
+
     # RAW persisted schema version (bypasses the DEFAULTS overlay, which would always
     # report the current one). nil = no settings persisted yet (fresh deploy — nothing
     # to migrate); an Integer otherwise, 0 for a pre-versioning record.