insika 0.1.0 → 0.3.0

data/lib/insika/shadow_pair_store.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+module Insika
+  # C2 — one durable record per mirrored exchange (shadow mode),
+  # written by TWO INDEPENDENT HALVES: ours at the turn's terminal, the
+  # incumbent's at the mirror. Both land on the same key — a digest of
+  # (channel, external_id, event_id), deterministic and order-free — so the two
+  # writers converge without an index and without ordering assumptions.
+  #
+  # It stores and it counts; it does not judge, does not fold a verdict, does
+  # not know what the criterion says.
+  #
+  # Status transitions (never backwards):
+  #
+  #                 ┌─ record_incumbent ─┐
+  #   (nothing) ────┤                    ├─▶ open ─▶ complete ─▶ judged
+  #                 └─ record_ours ─────┘       └─▶ silent   (never judged)
+  #                                             └─▶ incomplete (expire)
+  class ShadowPairStore
+    SCOPE = "shadow_pairs"
+    KEY_PREFIX = "pair:"
+
+    STATUSES = %i[open complete silent judged incomplete].freeze
+
+    Pair = Data.define(
+      :id, :channel, :agent, :session_id, :task_id, :event_id,
+      :inbound, :incumbent_reply, :insika_reply,
+      :status, :verdict, :criterion_sha, :created_at, :updated_at
+    ) do
+      def complete?      = %i[complete silent].include?(status)
+      def judged?        = status == :judged
+      def outcome        = verdict && verdict["outcome"]
+      def human_assisted? = verdict && verdict["vs"] == "human-assisted"
+    end
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # The correlation key BOTH writers compute independently. SHA-256 hex of
+    # "<channel>\0<external_id>\0<event_id>", truncated to 32 — deterministic,
+    # order-free, and it keeps a phone number out of the store's key space.
+    def self.key_for(channel:, external_id:, event_id:)
+      Digest::SHA256.hexdigest("#{channel}\0#{external_id}\0#{event_id}")[0, 32]
+    end
+
+    # Our half. Upsert: creates the record or fills our fields on the incumbent's.
+    # `reply` may be "" — a turn that published nothing (halt_when, an out-of-band
+    # tool) is recorded as :silent rather than left invisible. -> Pair
+    def record_ours(id:, channel:, agent:, session_id:, task_id:, event_id:,
+                    inbound:, reply:, criterion_sha:)
+      upsert(id) do |record, created|
+        record["channel"] = channel.to_s
+        record["event_id"] = event_id.to_s
+        record["agent"] = agent
+        record["session_id"] = session_id&.to_s
+        record["task_id"] = task_id&.to_s
+        record["inbound"] = inbound.to_s
+        record["insika_reply"] = reply.to_s
+        record["criterion_sha"] = criterion_sha
+        created
+      end
+    end
+
+    # The incumbent's half (the mirror contract). Same upsert shape; the fields
+    # this half owns are the reply and, on first write, the timestamp the mirror
+    # reports. Never overwrites our half's fields. First-write-wins is enforced
+    # HERE, inside the transaction: the customer received ONE reply, and two
+    # concurrent mirror retries must not let the second rewrite the evidence.
+    # -> Pair
+    def record_incumbent(id:, channel:, event_id:, external_id:, reply:, at: nil)
+      upsert(id, at: at) do |record, created|
+        record["channel"] = channel.to_s
+        record["event_id"] = event_id.to_s
+        record["incumbent_reply"] = reply.to_s if record["incumbent_reply"].nil?
+        created
+      end
+    end
+
+    # -> Pair | nil
+    def find(id)
+      record = @store.get(SCOPE, key_for(id))
+      record && to_pair(record)
+    end
+
+    # Lazy scan over a SNAPSHOT of the keys (deleting under a live enumeration
+    # would skip records — the same rule OutboxStore applies).
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      @store.list(SCOPE, KEY_PREFIX).each do |key|
+        record = @store.get(SCOPE, key)
+        yield to_pair(record) if record
+      end
+    end
+
+    # -> [Pair] created at or after `time`.
+    def since(time)
+      cutoff = time.utc.iso8601
+      each.select { |p| p.created_at.to_s >= cutoff }
+    end
+
+    # -> [Pair] status :complete, oldest first — the judging queue. `silent`
+    # pairs are NEVER here:   finding that pairwise is
+    # systematically unfair to a tool that delivers out of band is not
+    # something to average away.
+    def unjudged(limit: nil, agent: nil)
+      pairs = each.select { |p| p.status == :complete }
+                   .sort_by { |p| p.created_at.to_s }
+      pairs = pairs.select { |p| p.agent.to_s == agent.to_s } if agent
+      limit ? pairs.first(limit.to_i) : pairs
+    end
+
+    # -> { open:, complete:, silent:, judged:, incomplete: }
+    def counts(since: nil)
+      pairs = since ? self.since(since) : each.to_a
+      STATUSES.to_h { |s| [s, pairs.count { |p| p.status == s }] }
+    end
+
+    # The panel's Verdict as data. status -> :judged. -> Pair
+    def record_verdict(id, verdict:)
+      @store.transaction do
+        key = key_for(id)
+        record = @store.get(SCOPE, key)
+        raise Insika::NotFoundError, "shadow pair not found: #{id}" unless record
+
+        record["verdict"] = Coercion.deep_stringify(verdict)
+        record["status"] = "judged"
+        record["updated_at"] = timestamp
+        @store.set(SCOPE, key, record)
+        to_pair(record)
+      end
+    end
+
+    # An `open` pair older than the cutoff will never complete. -> count moved.
+    # `complete`/`silent`/`judged` are never touched. Update-style only: a pair
+    # deleted between the scan and the write (retention, LGPD purge) is left
+    # deleted — an upsert here would resurrect it as a ghost :incomplete record
+    # carrying none of its fields.
+    def expire(older_than:)
+      cutoff = older_than.utc.iso8601
+      moved = 0
+      each.select { |p| p.status == :open && p.created_at.to_s < cutoff }.each do |pair|
+        @store.transaction do
+          key = key_for(pair.id)
+          record = @store.get(SCOPE, key)
+          next unless record && record["status"] == "open"
+
+          record["status"] = "incomplete"
+          record["updated_at"] = timestamp
+          @store.set(SCOPE, key, record)
+          moved += 1
+        end
+      end
+      moved
+    end
+
+    # -> Integer. Keys only, no record materialization — a count of pairs must
+    # not pay for customer text (doctor's shadow-off check, the Studio).
+    def size = @store.list(SCOPE, KEY_PREFIX).length
+
+    # LGPD / retention (C9): drops every pair of these sessions, whatever its
+    # status — the pair holds the customer's own words. -> count removed.
+    def purge_sessions(session_ids)
+      wanted = Array(session_ids).map(&:to_s)
+      return 0 if wanted.empty?
+
+      doomed = each.select { |p| wanted.include?(p.session_id.to_s) }
+      doomed.each { |p| @store.delete(SCOPE, key_for(p.id)) }
+      doomed.size
+    end
+
+    # Retention: pairs created before the cutoff, TERMINAL statuses only
+    # (`judged`/`incomplete`) — an `open`/`complete` record older than the
+    # window is still someone's unjudged evidence. -> count removed.
+    def delete_older_than(time)
+      cutoff = time.utc.iso8601
+      doomed = each.select do |p|
+        %i[judged incomplete].include?(p.status) && p.created_at.to_s < cutoff
+      end
+      doomed.each { |p| @store.delete(SCOPE, key_for(p.id)) }
+      doomed.size
+    end
+
+    private
+
+    # The shared upsert: read -> merge only the fields THIS half owns (never
+    # overwrite the other's with nil) -> recompute status -> write. Runs inside
+    # Store#transaction so two halves landing in the same instant serialize on
+    # the backend's lock — the same claim mechanic OutboxStore#claim uses.
+    def upsert(id, at: nil, &fill)
+      @store.transaction do
+        key = key_for(id)
+        record = @store.get(SCOPE, key)
+        created = record.nil?
+        unless record
+          record = {
+            "id" => id.to_s, "channel" => nil, "agent" => nil, "session_id" => nil,
+            "task_id" => nil, "event_id" => nil, "inbound" => nil,
+            "incumbent_reply" => nil, "insika_reply" => nil, "status" => "open",
+            "verdict" => nil, "criterion_sha" => nil,
+            "created_at" => arrival_time(at), "updated_at" => timestamp
+          }
+        end
+        fill.call(record, created)
+        record["status"] = status_for(record)
+        record["updated_at"] = timestamp
+        @store.set(SCOPE, key, record)
+        to_pair(record)
+      end
+    end
+
+    # Status recomputation, in one place (never backwards — a judged pair stays
+    # judged, an expired one stays incomplete):
+    def status_for(record)
+      return record["status"] if %w[judged incomplete].include?(record["status"])
+      return "open" if record["insika_reply"].nil? || record["incumbent_reply"].nil?
+      return "silent" if record["insika_reply"].to_s.strip.empty?
+
+      "complete"
+    end
+
+    def key_for(id) = "#{KEY_PREFIX}#{id}"
+
+    # The mirror's reported time on first write; nil = now. A String rides
+    # through as-is (it is the wire format); a Time is normalized to ISO8601.
+    # A String is ALSO normalized to UTC ISO8601: the mirrors report local
+    # offsets (+09:00, -03:00) and every comparison against created_at
+    # (since/expire/retention/unjudged ordering) is lexicographic — two offsets
+    # would make those comparisons lie. Unparseable input keeps the old
+    # ride-through behaviour rather than refusing the pair.
+    def arrival_time(at)
+      return timestamp if at.nil?
+      return at.utc.iso8601 unless at.is_a?(String)
+
+      Time.iso8601(at).utc.iso8601
+    rescue ArgumentError
+      at
+    end
+
+    def to_pair(record)
+      Pair.new(
+        id: record["id"], channel: record["channel"], agent: record["agent"],
+        session_id: record["session_id"], task_id: record["task_id"],
+        event_id: record["event_id"], inbound: record["inbound"],
+        incumbent_reply: record["incumbent_reply"], insika_reply: record["insika_reply"],
+        status: record["status"].to_sym, verdict: record["verdict"],
+        criterion_sha: record["criterion_sha"],
+        created_at: record["created_at"], updated_at: record["updated_at"]
+      )
+    end
+
+    def timestamp = Time.now.utc.iso8601
+  end
+end

data/lib/insika/shutdown.rb

@@ -1,15 +1,15 @@
 # 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
+  # shutdown is a drain, not a kill (docs/DEPLOY.md, process model
+  # 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).
+  # (side-effect skip on resume is what makes that replay safe).
   #
   # 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
@@ -27,7 +27,7 @@ module Insika
     # 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
+    # `executors:` 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

data/lib/insika/skill_catalog.rb

@@ -11,7 +11,16 @@ module Insika
   # Consumed by the Executor (skill_catalog:) and by stage 3
   # (effective/format_for_prompt).
   class SkillCatalog
-    Skill = Data.define(:name, :description, :path, :body)
+    # Eagerness is NOT here. It used to be a frontmatter flag, i.e. a property of the
+    # SKILL — but skills are shared between agents, so one flag forced one decision
+    # onto every allowlist holding the skill. It is a property of the AGENT
+    # (`profile.skills_eager`, see #eager_for).
+    #
+    # companions: names of the skills this one cannot work without. Injecting or
+    # loading a skill brings them along, so the half-recipe state cannot be assembled —
+    # a reference table arriving without the procedure that reads it is worse than
+    # nothing, because the model then never asks for the other half.
+    Skill = Data.define(:name, :description, :path, :body, :triggers, :companions)
 
     # roots ordered by PRECEDENCE (highest first): workspace, managed,
     # bundled. Same name in more than one root: the first wins.
@@ -22,37 +31,97 @@ module Insika
     def initialize(roots, store: nil)
       @roots = Array(roots)
       @store = store
-      @skills = load_all
+      @skills, @agent_skills = load_all
     end
 
-    def all
-      @skills.values
+    # The SkillStore the catalog overlays — the composition root hands it to
+    # the harvest (the dedup reads the AUTHORED skills the catalog serves).
+    attr_reader :store
+
+    # `agent` (an agent id) resolves the AGENT SCOPE first, then the shared one — the
+    # same precedence chain the catalog already runs for store-over-disk and
+    # workspace-over-managed-over-bundled, with one more dimension.
+    #
+    # Three cases fall out of that one rule: SHARED (only the shared record exists),
+    # OVERRIDE (both exist, the agent's wins) and AGENT-PRIVATE (only the agent record
+    # exists — invisible elsewhere, and its name may collide freely).
+    #
+    # Without `agent` the shared scope is all there is, which is what every caller
+    # that has no agent in hand (the Studio's shared editor, a bare catalog) means.
+    def all(agent: nil)
+      shared = @skills
+      overrides = agent_scope(agent)
+      return shared.values if overrides.empty?
+
+      shared.merge(overrides).values
     end
 
-    def find(name)
-      @skills[name.to_s]
+    def find(name, agent: nil)
+      agent_scope(agent)[name.to_s] || @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
+      @skills, @agent_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 }
+    # Per-agent allowlist: nil -> all | [] -> none | [names] -> subset. `agent`
+    # selects WHICH body each allowed name resolves to (see #find); the allowlist is
+    # by NAME either way, so specializing a skill never touches the allowlist.
+    def effective(skills_policy, agent: nil)
+      Allowlist.filter(all(agent: agent), skills_policy) { |s| s.name }
     end
 
+    # THE single definition of "always in the prompt", consulted by all three
+    # surfaces that must agree: the body provider (injects these), the level-1
+    # catalog (hides them) and load_skill (refuses them). Split the rule across three
+    # files and they drift — which is the failure this whole feature came from.
+    #
+    # `profile.skills_eager` — a PER-AGENT decision, so a shared skill stays shared:
+    #   nil | false  -> none (progressive disclosure; the default)
+    #   true         -> every allowed skill (blanket; only for a corpus that fits the budget)
+    #   [names]      -> exactly these
+    #
+    # Deliberately NOT `Allowlist.filter`: there nil means ALL, which is the safe
+    # default for `skills`/`tools_allow` where nil is "no policy". Here nil must mean
+    # NONE — an unconfigured agent waking up with every skill body on every turn is
+    # the opposite of a safe default. A name that is not in the agent's `skills`
+    # allowlist is a silent no-op here (the intersection with `effective`); `doctor`
+    # flags it, because the operator who wrote the name meant it.
+    def eager_for(profile)
+      allowed = effective(profile.skills, agent: profile.id)
+      spec = profile.skills_eager
+      return allowed if blanket?(spec)
+      return [] if spec.nil? || spec == false
+
+      names = Array(spec).map { |n| n.to_s.strip }
+      allowed.select { |s| names.include?(s.name) }
+    end
+
+    # The complement: what the model still has to ASK for — and therefore what the
+    # level-1 list advertises and load_skill will serve.
+    def lazy_for(profile) = effective(profile.skills, agent: profile.id) - eager_for(profile)
+
     # Level 1: compact list injected into the system prompt. Metadata only.
     # Receives the set already filtered by the agent.
+    #
+    # `when=` carries the skill's `triggers:` — THE ROUTING TABLE, GENERATED. What
+    # actually made activation reliable on the pilot was a hand-written companion file
+    # listing each skill with its trigger phrases, and nothing checked it against the
+    # catalog: a skill created at 11:28 was invisible to a table written the day
+    # before, and the model obeyed the table. Rendering the same information from the
+    # catalog means it cannot disagree with the allowlist — a newly allowed skill
+    # appears the moment it is allowed. Detecting that drift would have been strictly
+    # worse than removing its source.
     def format_for_prompt(skills = all)
       return "" if skills.empty?
 
       entries = skills.map do |s|
-        %(  <skill name="#{s.name}">#{s.description}</skill>)
+        when_attr = Array(s.triggers).empty? ? "" : %( when="#{Array(s.triggers).join('; ')}")
+        %(  <skill name="#{s.name}"#{when_attr}>#{s.description}</skill>)
       end.join("\n")
 
       <<~PROMPT.strip
@@ -60,13 +129,24 @@ module Insika
         #{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.
+        Before ANY reply or tool call: scan the skills above. If one matches
+        or is even partially relevant to the task, you MUST call
+        `load_skill("name")` FIRST and follow what it returns. Err on the
+        side of loading. Only skip when genuinely none apply.
       PROMPT
     end
 
     private
 
+    # The blanket switch, tolerant of the strings a form / JSON round-trip produces
+    # ("1" from a checkbox, "true" from a pack) — same reading as
+    # AgentProfile#stream_public?. Anything else (a list, nil, false) is not blanket.
+    def blanket?(spec) = Coercion.truthy?(spec)
+
+    # An agent's override index; {} for a nil agent or one that specialized nothing.
+    def agent_scope(agent) = agent.nil? ? {} : (@agent_skills[agent.to_s] || {})
+
+    # -> [shared index, { agent_id => index }].
     def load_all
       found = {}
       @roots.each do |root|
@@ -78,7 +158,7 @@ module Insika
         end
       end
       overlay_store(found)
-      found
+      [found, load_agent_scopes]
     end
 
     # Store skills overlay the on-disk ones (authored > seed). Sentinel path
@@ -87,27 +167,58 @@ module Insika
       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
+        skill = parse_content(content.to_s, path: "store:#{name}", key: name)
+        found[name.to_s] = skill if skill # Store wins
       end
     end
 
-    def parse_content(raw, path:)
+    # Per-agent overrides / private skills, one index per agent. A store that predates
+    # the agent dimension answers nothing here, so this is {} and every lookup falls
+    # straight through to the shared scope.
+    def load_agent_scopes
+      return {} unless @store.respond_to?(:agents)
+
+      @store.agents.each_with_object({}) do |agent, acc|
+        index = {}
+        @store.all(agent: agent).each do |name, content|
+          skill = parse_content(content.to_s, path: "store:#{agent}/#{name}", key: name)
+          index[name.to_s] = skill if skill
+        end
+        acc[agent.to_s] = index unless index.empty?
+      end
+    end
+
+    # `key` = THE STORE POSITION, and it wins over the frontmatter `name:`. An override
+    # authored for one agent still says `name: escalation-to-human` inside — that is
+    # deliberate, it is the same skill specialized — and indexing by the parsed name
+    # would clobber the shared record globally, which is the exact bug the agent scope
+    # exists to fix. It also makes a pack whose directory name and frontmatter name
+    # disagree resolvable: the allowlist is written from the directory.
+    def parse_content(raw, path:, key: nil)
       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
+      name = key || meta["name"]
+      return nil unless name && Coercion.present?(meta["name"])
 
       Skill.new(
         name: name.to_s,
         description: meta["description"].to_s,
         path: path,
-        body: match[2].strip
+        body: match[2].strip,
+        triggers: parse_list(meta["triggers"]),
+        companions: parse_list(meta["companions"])
       )
     end
+
+    # `triggers:` / `companions:` frontmatter. YAML list, or comma-separated string
+    # under the lenient parse (which yields the whole value as one String).
+    def parse_list(raw)
+      list = raw.is_a?(String) ? raw.split(",") : Array(raw)
+      list.map { |t| t.to_s.strip }.reject(&:empty?)
+    end
   end
 end

data/lib/insika/skill_store.rb

@@ -3,20 +3,37 @@
 require "time"
 
 module Insika
-  # AUTHORED shared skills.
+  # AUTHORED skills, in two scopes.
   # 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"):
+  # SHARED scope (`agent:` omitted) — one record per skill in the ConfigStore
+  # (scope "skills"), keyed by the skill name:
   #   { "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.
+  # AGENT scope (`agent:` given) — one record per AGENT (scope "agent_skills"), the
+  # skills nested under it, exactly the AgentFileStore shape:
+  #   { "skills" => { "<name>" => { "content" =>, "updated_at" =>, "history" => [] } } }
+  #
+  # The agent dimension is a SECOND ARGUMENT, never part of the key. A composite
+  # `"agent/name"` key would put a `/` inside what the Studio serves as a single path
+  # segment (`GET /skills/:name`, the editor, the versions list) — the class of route
+  # bug that ships green and 404s in production. Two arguments become two route
+  # segments (`/agents/:id/skills/:name`) and nothing needs encoding.
+  #
+  # Two scopes and not one: the shared records are untouched by the arrival of the
+  # agent dimension, so there is no migration and a live deployment keeps serving
+  # exactly what it served.
+  #
+  # THE STORE POSITION IS THE IDENTITY. Which scope a record sits in — and under which
+  # key — is what decides which skill it is; the frontmatter `name:` inside an override
+  # stays the bare shared name. See SkillCatalog#find.
   class SkillStore
     SCOPE = "skills"
+    AGENT_SCOPE = "agent_skills"
     HISTORY_MAX = 20
 
     def initialize(config_store:)
@@ -24,48 +41,79 @@ module Insika
     end
 
     # -> String | nil (complete SKILL.md).
-    def get(name)
-      record(name)&.fetch("content", nil)
+    def get(name, agent: nil)
+      record(name, agent)&.fetch("content", nil)
     end
 
-    # -> [String] names, lexicographic order.
-    def names = @cs.keys(SCOPE)
+    # -> [String] names in the scope, lexicographic order.
+    def names(agent: nil)
+      agent.nil? ? @cs.keys(SCOPE) : agent_skills(agent).keys.sort
+    end
 
-    # -> { name => content } of all authored skills.
-    def all
-      @cs.keys(SCOPE).each_with_object({}) { |n, acc| acc[n] = get(n) }
+    # -> { name => content } of the scope's authored skills.
+    def all(agent: nil)
+      names(agent: agent).each_with_object({}) { |n, acc| acc[n] = get(n, agent: agent) }
     end
 
+    # -> [String] every agent that has specialized at least one skill. What the
+    # catalog overlays and `doctor` sweeps.
+    def agents = @cs.keys(AGENT_SCOPE).sort
+
     # Writes (upsert). create_only refuses to overwrite. -> Hash (the stored record).
-    def write(name, content, create_only: false)
+    def write(name, content, agent: nil, create_only: false)
       key = name.to_s
-      current = @cs.get(SCOPE, key)
-      raise Insika::ValidationError, "skill '#{key}' already exists" if create_only && current
+      current = record(key, agent)
+      raise Insika::ValidationError, "skill '#{key}' already exists#{" for agent '#{agent}'" if agent}" if create_only && current
 
       rec = build_record(content.to_s, current)
-      @cs.put(SCOPE, key, rec)
+      put(key, rec, agent)
       rec
     end
 
     # -> bool (did it exist?).
-    def delete(name) = @cs.delete(SCOPE, name.to_s)
+    def delete(name, agent: nil)
+      key = name.to_s
+      return @cs.delete(SCOPE, key) if agent.nil?
+
+      wrapper = @cs.get(AGENT_SCOPE, agent.to_s)
+      return false unless wrapper&.dig("skills", key)
+
+      wrapper["skills"].delete(key)
+      @cs.put(AGENT_SCOPE, agent.to_s, wrapper)
+      true
+    end
 
     # -> [ { "content" =>, "at" => } ] most recent first.
-    def versions(name) = record(name)&.fetch("history", []) || []
+    def versions(name, agent: nil) = record(name, agent)&.fetch("history", []) || []
 
     # Restores version `index` as the current content (a new write). -> Hash.
-    def restore(name, index)
-      hist = versions(name)
+    def restore(name, index, agent: nil)
+      hist = versions(name, agent: agent)
       i = Integer(index)
-      raise Insika::NotFoundError, "skill '#{name}' not found" unless record(name)
+      raise Insika::NotFoundError, "skill '#{name}' not found" unless record(name.to_s, agent)
       raise Insika::ValidationError, "version #{index} does not exist" if i.negative? || i >= hist.length
 
-      write(name, hist[i]["content"])
+      write(name, hist[i]["content"], agent: agent)
     end
 
     private
 
-    def record(name) = @cs.get(SCOPE, name.to_s)
+    def record(name, agent)
+      return @cs.get(SCOPE, name.to_s) if agent.nil?
+
+      agent_skills(agent)[name.to_s]
+    end
+
+    def put(key, rec, agent)
+      return @cs.put(SCOPE, key, rec) if agent.nil?
+
+      wrapper = @cs.get(AGENT_SCOPE, agent.to_s) || { "skills" => {} }
+      wrapper["skills"] ||= {}
+      wrapper["skills"][key] = rec
+      @cs.put(AGENT_SCOPE, agent.to_s, wrapper)
+    end
+
+    def agent_skills(agent) = (@cs.get(AGENT_SCOPE, agent.to_s) || {})["skills"] || {}
 
     def build_record(content, current)
       history = current ? current.fetch("history", []) : []