insika 0.0.1 → 0.1.0

data/lib/insika/session_store.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # Domain store for sessions. Persists transcript + vars
+  # over an injected Insika::Store, with a fixed schema
+  # `session:<id>` in the "sessions" scope.
+  #
+  # The persisted transcript is the SOURCE OF TRUTH for reconstruction; live
+  # events are just delivery state. The message shape
+  # (`{"role"=>, "content"=>}`, role ∈ user|assistant|system|tool) is the
+  # same one `Runner#seed_history` already consumes — the Executor converts nothing.
+  #
+  # Normalizes symbol→string on WRITE (the backend only guarantees round-trip of
+  # JSON types); READ returns the data as it comes from the backend
+  # (string keys), never symmetrizing back to symbols.
+  class SessionStore
+    include Coercion
+
+    SCOPE = "sessions"
+    KEY_PREFIX = "session:"
+
+    Session = Data.define(:id, :messages, :vars, :memory_refs,
+                          :created_at, :updated_at)
+
+    # store: any Insika::Store (Memory, SQLite, ...) — injected by the
+    # composition root (config/wiring.rb). SessionStore does not know the
+    # concrete backend.
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> Session; ArgumentError if id already exists (a duplicate session is a
+    # domain violation — it never overwrites silently).
+    def create(id: SecureRandom.uuid, vars: {})
+      key = key_for(id)
+      raise ArgumentError, "session already exists: #{id}" unless @store.get(SCOPE, key).nil?
+
+      now = timestamp
+      record = {
+        "id" => id.to_s,
+        "messages" => [],
+        "vars" => deep_stringify(vars),
+        "memory_refs" => [],
+        "created_at" => now,
+        "updated_at" => now
+      }
+      @store.set(SCOPE, key, record)
+      to_session(record)
+    end
+
+    # -> Session | nil
+    def find(id)
+      record = @store.get(SCOPE, key_for(id))
+      record && to_session(record)
+    end
+
+    # -> Session (transcript += messages). Read-modify-write on the task's own
+    # fiber, without a lock. Each message gets an "at" (ISO8601 UTC) if not
+    # provided. NotFoundError if the session does not exist.
+    #
+    # CONCURRENCY LIMITATION (§11 R2c): the RMW (read record -> += -> set) is
+    # atomic ONLY because the SessionActor serializes turns of the same session
+    # (one owner at a time). That serialization exists solely in SUPERVISED mode
+    # (the actor loop lives on the supervisor). Two concurrent send_message on the
+    # same session_id OUTSIDE that path (e.g. calling append_messages directly, or
+    # 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)
+      record = fetch!(id)
+      incoming = (messages.is_a?(Hash) ? [messages] : Array(messages))
+                 .map { |msg| stamp(deep_stringify(msg)) }
+      record["messages"] += incoming
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_session(record)
+    end
+
+    # -> Session (SHALLOW merge: an existing nested key is replaced wholesale,
+    # not merged). NotFoundError if absent.
+    def update_vars(id, vars)
+      record = fetch!(id)
+      record["vars"] = record["vars"].merge(deep_stringify(vars))
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_session(record)
+    end
+
+    # -> bool (delegates to the backend: false for a nonexistent id)
+    def delete(id)
+      @store.delete(SCOPE, key_for(id))
+    end
+
+    # -> enumerates ids without the "session:" prefix. Without a block,
+    # returns an Enumerator.
+    def each_id
+      return enum_for(:each_id) unless block_given?
+
+      @store.list(SCOPE, KEY_PREFIX).each do |key|
+        yield key.delete_prefix(KEY_PREFIX)
+      end
+    end
+
+    private
+
+    def key_for(id)
+      "#{KEY_PREFIX}#{id}"
+    end
+
+    # Loads the raw record; NotFoundError if absent (nonexistent session ->
+    # HTTP 404). Backend errors (StoreError) propagate without re-wrapping.
+    def fetch!(id)
+      record = @store.get(SCOPE, key_for(id))
+      raise Insika::NotFoundError, "session not found: #{id}" if record.nil?
+
+      record
+    end
+
+    def to_session(record)
+      Session.new(
+        id: record["id"],
+        messages: record["messages"],
+        vars: record["vars"],
+        memory_refs: record["memory_refs"],
+        created_at: record["created_at"],
+        updated_at: record["updated_at"]
+      )
+    end
+
+    # Stamps "at" (ISO8601 UTC) on the message when absent; preserves whatever is provided.
+    def stamp(message)
+      message["at"] ||= timestamp
+      message
+    end
+
+    def timestamp
+      Time.now.utc.iso8601
+    end
+  end
+end

data/lib/insika/settings_store.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+module Insika
+  # GENERAL deploy settings: timeouts, streaming and
+  # compaction. A single record in the ConfigStore (scope "settings", key "general").
+  # A read always returns the DEFAULTS overlaid by whatever was authored — so
+  # a brand-new deploy (empty store) already responds with coherent config, and the Studio
+  # only persists the delta. Shallow merge at the top, deep in `compaction` (sub-hash).
+  #
+  # Not to be confused with the transport `CONFIG` (bind/port/token, ENV+freeze at
+  # boot): this is editable RUNTIME config, durable in the same backend.
+  class SettingsStore
+    SCOPE = "settings"
+    KEY   = "general"
+
+    # STRICT config, settings layer (item 23 / §8.1 — "no silent config compat: every
+    # schema migration explicit"). The settings record carries a `schema_version`;
+    # every shape change is a numbered migration here, applied ONLY by the explicit
+    # `migrate!` (Studio settings saves never silently reinterpret old-shaped data).
+    # v1 is the baseline: a pre-versioning record (no `schema_version`) reads as 0 and
+    # `insika doctor --fix` stamps it to 1. Add a real change as MIGRATIONS[2] = proc
+    # and bump SCHEMA_VERSION.
+    SCHEMA_VERSION = 1
+    MIGRATIONS = {}.freeze # target_version(Integer) => ->(record_hash){ migrated_hash }
+
+    DEFAULTS = {
+      "schema_version" => SCHEMA_VERSION,
+      "streaming" => true,
+      "request_timeout" => 120,
+      "max_retries" => 2,
+      "turn_timeout" => 120,
+      "tool_timeout" => 30,
+      "compaction" => { "enabled" => false, "keep_last" => 20 },
+      # LLM config v2 (§10). Platform-wide model layer, resolved by the
+      # ModelResolver under an agent that pins no model of its own:
+      #   default_model/default_provider -> the platform default (Chat > Agent > HERE)
+      #   fallback_models -> ordered chain ["provider/model" | "model", ...] tried
+      #                      when the primary is NOT a user pin (source semantics)
+      #   utility_model   -> slot for cheap internal tasks (titles, distillation,
+      #                      compaction); reserved for later wiring.
+      "default_model" => nil,
+      "default_provider" => nil,
+      "fallback_models" => [],
+      "utility_model" => nil,
+      # Reasoning control (§10, 4-layer: Chat > Agent > Model > Global). `thinking`
+      # is the GLOBAL default (off/on/low/medium/high; nil = provider default);
+      # `model_params` is the PER-MODEL layer, a map "<provider/model>"|"<model>" ->
+      # { "thinking" => ... }. Both resolved by the ModelResolver.
+      "thinking" => nil,
+      "model_params" => {},
+      # Evals (RFC-0008, panel by RFC-0013 §3.9). The GRADERS are platform config, so
+      # the operator picks them in the Studio instead of remembering a CLI flag:
+      #   judges        -> [{ "model" =>, "provider" => }, …]. [] = deterministic
+      #                    asserts only (rubric'd cases read as judge_pending).
+      #   aggregate     -> median | mean | min — how the panel's scores become the one
+      #                    the report and the baseline read.
+      #   min_agreement -> fraction of judges that must pass for the case to pass.
+      #   quorum        -> samples per judge (variance), on top of the panel.
+      #   tolerance     -> max judge-score drop before it counts as a regression.
+      # Additive key: reads overlay DEFAULTS, so no numbered migration is due (only a
+      # later SHAPE change to this key would earn one).
+      "evals" => {
+        "judges" => [],
+        "aggregate" => "median",
+        "min_agreement" => 0.5,
+        "quorum" => 1,
+        "tolerance" => 0.05
+      },
+      # Edge limits (item 33 / §12 G7) — the platform layer of the EdgeLimiter.
+      # nil/0 = off (opt-in). chat_rate_limit = turn attempts per chat per
+      # chat_rate_window (s); agent_token_ceiling = total tokens per agent per
+      # agent_token_window (s). limit_response overrides the safe reply.
+      # Per-agent overrides live in profile.limits (same keys, sans windows).
+      "edge" => {
+        "chat_rate_limit" => nil,
+        "chat_rate_window" => 60,
+        "agent_token_ceiling" => nil,
+        "agent_token_window" => 86_400,
+        "limit_response" => nil
+      }
+    }.freeze
+
+    def initialize(config_store:)
+      @cs = config_store
+    end
+
+    # -> Hash (defaults overlaid by the authored values). String keys (Store contract).
+    def get
+      deep_merge(DEFAULTS, stored)
+    end
+
+    # Merges the patch over the current one and persists. -> Hash (resulting settings).
+    # Unknown keys are preserved (the Studio decides the screen's schema).
+    def update(patch)
+      merged = deep_merge(get, stringify(patch || {}))
+      @cs.put(SCOPE, KEY, merged)
+      merged
+    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.
+    def stored_schema_version
+      raw = stored
+      return nil if raw.empty?
+
+      Integer(raw["schema_version"] || 0)
+    end
+
+    # Which numbered migrations still need to run. [] when fresh or already current.
+    def pending_migrations
+      from = stored_schema_version
+      return [] if from.nil? || from >= SCHEMA_VERSION
+
+      ((from + 1)..SCHEMA_VERSION).to_a
+    end
+
+    # Applies the pending migrations EXPLICITLY (in order) and stamps the version. No-op
+    # when fresh or already current. -> resulting schema_version (Integer).
+    def migrate!
+      data = stored
+      return SCHEMA_VERSION if data.empty?
+
+      pending_migrations.each do |version|
+        migration = MIGRATIONS[version]
+        data = stringify(migration.call(data)) if migration
+      end
+      data["schema_version"] = SCHEMA_VERSION
+      @cs.put(SCOPE, KEY, data)
+      SCHEMA_VERSION
+    end
+
+    private
+
+    def stored
+      @cs.get(SCOPE, KEY) || {}
+    end
+
+    def deep_merge(base, override)
+      base.merge(override) do |_key, a, b|
+        a.is_a?(Hash) && b.is_a?(Hash) ? deep_merge(a, b) : b
+      end
+    end
+
+    def stringify(obj)
+      case obj
+      when Hash then obj.each_with_object({}) { |(k, v), acc| acc[k.to_s] = stringify(v) }
+      when Array then obj.map { |v| stringify(v) }
+      when Symbol then obj.to_s
+      else obj
+      end
+    end
+  end
+end

data/lib/insika/shutdown.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Insika
+  # RFC-0016 A3 — shutdown is a drain, not a kill (docs/DEPLOY.md, process model
+  # item 4). The serving arms install this around the Executor. On the first
+  # SIGTERM/SIGINT the process stops accepting new turns (`Executor#begin_drain!`
+  # — a turn arriving mid-drain is left `:queued` for the next boot's recovery)
+  # and waits up to `timeout` seconds for the in-flight ones; only then does the
+  # ordinary stop proceed. A second signal skips the wait — the operator insisting
+  # means now. Whatever the deadline abandons dies `:running` with the process and
+  # the next boot generation's task sweep replays it from its checkpoint
+  # (side-effect skip on resume is what makes that replay safe, RFC-0006).
+  #
+  # Mechanics, because trap context is narrow: the handler writes ONE byte into a
+  # self-pipe and returns. A plain watcher THREAD — not a fiber: at install time
+  # the serving reactor may not exist yet, and the drain must not depend on it —
+  # blocks on that pipe, runs the drain, and then delivers the stop the trap
+  # withheld by raising Interrupt in the serving thread. That is exactly the
+  # exception async-container's own trap would have raised, so everything
+  # downstream (Falcon worker teardown, reactor close, Litestream's final sync)
+  # is unchanged; this class only buys the turns time before it.
+  class Shutdown
+    DEFAULT_TIMEOUT = 20 # seconds — the number DEPLOY.md records and entrypoint.sh builds on
+    POLL = 0.05
+
+    # The one-call form the serving arms use: resolves the deadline, sets the
+    # traps, parks the watcher. The CALLING thread is captured as the stop target
+    # — install from the thread that runs the server.
+    #
+    # `executors:` (RFC-0017 A4) drains N graphs on one signal. Signals are a
+    # PROCESS concern, and `Signal.trap` keeps only the last handler — so a second
+    # `install` per graph would silently leave the earlier graphs dying mid-turn.
+    # The host installs ONCE, naming every graph it embedded. `executor:` is the
+    # single-graph sugar every serving arm still uses.
+    def self.install(executor: nil, executors: nil, timeout: nil, logger: $stdout, signals: %w[INT TERM])
+      new(executors: executors || executor, timeout: timeout || default_timeout,
+          logger: logger).install!(signals)
+    end
+
+    # INSIKA_DRAIN_TIMEOUT (validated by EnvSchema); absent/garbage -> the default.
+    def self.default_timeout
+      Integer(EnvSchema.read("INSIKA_DRAIN_TIMEOUT").to_s)
+    rescue ArgumentError
+      DEFAULT_TIMEOUT
+    end
+
+    # `interrupt` is the injectable stop delivery (specs); the default raises
+    # Interrupt in `target`, the thread that installed the traps.
+    def initialize(executor: nil, executors: nil, timeout:, logger: $stdout,
+                   target: Thread.current, interrupt: nil)
+      @executors = Array(executors || executor)
+      @timeout = timeout
+      @logger = logger
+      @target = target
+      @interrupt = interrupt || -> { @target.raise(Interrupt) }
+      @reader, @writer = IO.pipe
+      @signaled = false
+    end
+
+    attr_reader :timeout
+
+    def install!(signals = %w[INT TERM])
+      signals.each { |sig| Signal.trap(sig) { signal_received } }
+      @thread = Thread.new { watch }
+      @thread.name = "insika-shutdown"
+      self
+    end
+
+    # Runs in TRAP context: a flag flip and a pipe write, nothing else — except
+    # when the drain is already underway, where a repeated signal means "stop
+    # waiting" and the Interrupt is delivered immediately.
+    def signal_received
+      return @interrupt.call if @signaled
+
+      @signaled = true
+      begin
+        @writer.write_nonblock("!")
+      rescue IOError, SystemCallError
+        nil # pipe gone (process already unwinding): nothing left to schedule
+      end
+    end
+
+    # The watcher's whole life: parked on the pipe until the first signal, then
+    # drain and hand the stop back to the normal path.
+    def watch
+      @reader.read(1)
+      drain
+      @interrupt.call
+    end
+
+    # Closes the intake and waits for the in-flight turns, bounded by the
+    # deadline. With N executors the intake of EVERY one closes first, before any
+    # waiting: draining them in sequence would let graph B keep taking turns while
+    # graph A spends the deadline. -> { drained: bool, abandoned: [task ids] }
+    def drain
+      @executors.each(&:begin_drain!)
+      log("shutdown: draining — #{in_flight.size} turn(s) in flight, deadline #{@timeout}s")
+      deadline = monotonic + @timeout
+      sleep(POLL) until in_flight.empty? || monotonic >= deadline
+
+      abandoned = in_flight
+      if abandoned.empty?
+        log("shutdown: drained clean")
+      else
+        log("shutdown: deadline reached — abandoning #{abandoned.size} turn(s); " \
+            "recovery replays them at the next boot")
+      end
+      { drained: abandoned.empty?, abandoned: abandoned }
+    end
+
+    private
+
+    # The turns still running across every graph this shutdown owns.
+    def in_flight = @executors.flat_map(&:in_flight)
+
+    def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    # Observability only: a logger failure must never alter the drain.
+    def log(message)
+      @logger&.puts(message)
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/insika/skill_catalog.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Insika
+  # OpenClaw / AgentSkills convention: each skill is a directory with a
+  # SKILL.md (YAML frontmatter + markdown body). Progressive disclosure:
+  # level 1 = name+description in the system prompt; level 2 = body loaded
+  # on demand by the load_skill tool.
+  #
+  # Consumed by the Executor (skill_catalog:) and by stage 3
+  # (effective/format_for_prompt).
+  class SkillCatalog
+    Skill = Data.define(:name, :description, :path, :body)
+
+    # roots ordered by PRECEDENCE (highest first): workspace, managed,
+    # bundled. Same name in more than one root: the first wins.
+    #
+    # store (optional): a SkillStore with the skills AUTHORED in the Studio.
+    # They overlay the on-disk ones (seed) — the Store wins, it is the source of truth.
+    # Nil = disk-only behavior, zero regression.
+    def initialize(roots, store: nil)
+      @roots = Array(roots)
+      @store = store
+      @skills = load_all
+    end
+
+    def all
+      @skills.values
+    end
+
+    def find(name)
+      @skills[name.to_s]
+    end
+
+    # Reloads from disk + Store and SWAPS the index atomically: an
+    # authored/edited skill takes effect without a restart. A turn in progress
+    # captured @skills at dispatch, so it does not see the swap mid-flight.
+    def reload
+      @skills = load_all
+      self
+    end
+
+    # Per-agent allowlist: nil -> all | [] -> none | [names] -> subset.
+    def effective(skills_policy)
+      Allowlist.filter(all, skills_policy) { |s| s.name }
+    end
+
+    # Level 1: compact list injected into the system prompt. Metadata only.
+    # Receives the set already filtered by the agent.
+    def format_for_prompt(skills = all)
+      return "" if skills.empty?
+
+      entries = skills.map do |s|
+        %(  <skill name="#{s.name}">#{s.description}</skill>)
+      end.join("\n")
+
+      <<~PROMPT.strip
+        <available_skills>
+        #{entries}
+        </available_skills>
+
+        Before acting on a task that matches a skill above, call the
+        `load_skill` tool with its name to load the complete instructions.
+      PROMPT
+    end
+
+    private
+
+    def load_all
+      found = {}
+      @roots.each do |root|
+        Dir.glob(File.join(root, "**", "SKILL.md")).sort.each do |file|
+          skill = parse_content(File.read(file, encoding: "UTF-8"), path: file)
+          next unless skill
+
+          found[skill.name] ||= skill # precedence: first root wins
+        end
+      end
+      overlay_store(found)
+      found
+    end
+
+    # Store skills overlay the on-disk ones (authored > seed). Sentinel path
+    # "store:<name>" — not a real file (load_skill uses `body`, not the path).
+    def overlay_store(found)
+      return unless @store
+
+      @store.all.each do |name, content|
+        skill = parse_content(content.to_s, path: "store:#{name}")
+        found[skill.name] = skill if skill # Store wins
+      end
+    end
+
+    def parse_content(raw, path:)
+      match = raw.match(/\A---\s*\n(.*?)\n---\s*\n(.*)\z/m)
+      return nil unless match
+
+      # Tolerant frontmatter: real packs have `: ` in the description prose, which
+      # strict YAML rejected (the pack would not load).
+      meta = Insika::Frontmatter.parse(match[1])
+      name = meta["name"]
+      return nil unless name
+
+      Skill.new(
+        name: name.to_s,
+        description: meta["description"].to_s,
+        path: path,
+        body: match[2].strip
+      )
+    end
+  end
+end

data/lib/insika/skill_store.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # AUTHORED shared skills.
+  # Holds the complete SKILL.md (frontmatter + body) in the durable Store. The
+  # SkillCatalog overlays these skills on top of the on-disk ones (seed), with the Store
+  # winning — so editing/creating a skill in the Studio takes effect without a restart (via reload).
+  #
+  # One record per skill in the ConfigStore (scope "skills"):
+  #   { "content" => "<entire SKILL.md>",
+  #     "updated_at" => iso8601,
+  #     "history" => [ { "content" =>, "at" => }, ... ] }
+  #
+  # The key is the skill's canonical name (the same as in the frontmatter). Versions like
+  # the AgentFileStore.
+  class SkillStore
+    SCOPE = "skills"
+    HISTORY_MAX = 20
+
+    def initialize(config_store:)
+      @cs = config_store
+    end
+
+    # -> String | nil (complete SKILL.md).
+    def get(name)
+      record(name)&.fetch("content", nil)
+    end
+
+    # -> [String] names, lexicographic order.
+    def names = @cs.keys(SCOPE)
+
+    # -> { name => content } of all authored skills.
+    def all
+      @cs.keys(SCOPE).each_with_object({}) { |n, acc| acc[n] = get(n) }
+    end
+
+    # Writes (upsert). create_only refuses to overwrite. -> Hash (the stored record).
+    def write(name, content, create_only: false)
+      key = name.to_s
+      current = @cs.get(SCOPE, key)
+      raise Insika::ValidationError, "skill '#{key}' already exists" if create_only && current
+
+      rec = build_record(content.to_s, current)
+      @cs.put(SCOPE, key, rec)
+      rec
+    end
+
+    # -> bool (did it exist?).
+    def delete(name) = @cs.delete(SCOPE, name.to_s)
+
+    # -> [ { "content" =>, "at" => } ] most recent first.
+    def versions(name) = record(name)&.fetch("history", []) || []
+
+    # Restores version `index` as the current content (a new write). -> Hash.
+    def restore(name, index)
+      hist = versions(name)
+      i = Integer(index)
+      raise Insika::NotFoundError, "skill '#{name}' not found" unless record(name)
+      raise Insika::ValidationError, "version #{index} does not exist" if i.negative? || i >= hist.length
+
+      write(name, hist[i]["content"])
+    end
+
+    private
+
+    def record(name) = @cs.get(SCOPE, name.to_s)
+
+    def build_record(content, current)
+      history = current ? current.fetch("history", []) : []
+      if current
+        history = [{ "content" => current["content"], "at" => current["updated_at"] }] + history
+        history = history.first(HISTORY_MAX)
+      end
+      { "content" => content, "updated_at" => Time.now.utc.iso8601, "history" => history }
+    end
+  end
+end