insika 0.0.1 → 0.1.0

data/lib/insika/overlay_tool_registry.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Insika
+  # DYNAMIC tool registry: composes the CODE registry (base, built at boot,
+  # immutable) with the DATA-DEFINED tools from the ToolStore. Drop-in for ToolRegistry —
+  # the Executor/ToolCatalog/ToolEnvelope only use entries/resolve/side_effect?. Phase 5,
+  # Step B / D2.
+  #
+  # Rules:
+  #   - COLLISION: the base (code) ALWAYS wins — a data-tool cannot hijack
+  #     the name of a code tool (security, R3). The authoring Command also
+  #     refuses to create with a colliding name (code_tool?), but the defense stays here.
+  #   - HOT: `reload` re-reads the store and swaps the dynamic index atomically — a
+  #     new/edited data-tool takes effect on the next turn without a restart (F5), mirroring
+  #     SkillCatalog.reload. An in-flight turn has already captured the index.
+  #   - PARITY (NF1): empty ToolStore ⇒ entries/resolve/side_effect? identical to the
+  #     pure base. The base (config/wiring.rb) does not even use the overlay — zero regression.
+  #
+  # The data-tools enter as NORMAL Registry::Entry (optional: false) — they obey
+  # the same per-agent allow/deny as code tools; exposure is the operator's
+  # (the /tools matrix), not automatic just because they are "data-defined".
+  class OverlayToolRegistry
+    def initialize(base:, tool_store:, http:, egress: Insika::EgressGuard, egress_options: {}, event_stream: nil)
+      @base = base
+      @tool_store = tool_store
+      @http = http
+      @egress = egress
+      @egress_options = egress_options
+      @event_stream = event_stream
+    end
+
+    # Base + dynamic, except dynamic ones that collide with the base (base wins).
+    def entries
+      @base.entries + dynamic.reject { |e| code_tool?(e.name) }
+    end
+
+    def names
+      (@base.names + dynamic.map(&:name)).uniq
+    end
+
+    # -> instance (base wins) | raise NotFoundError.
+    def resolve(name)
+      key = name.to_s
+      return @base.resolve(key) if code_tool?(key)
+
+      entry = dynamic.find { |e| e.name == key }
+      raise Insika::NotFoundError, "'#{name}' not registered in #{self.class}" unless entry
+
+      entry.factory.call
+    end
+
+    # -> bool; consumed by ToolEnvelope (checkpoint/skip-on-resume). Base wins.
+    def side_effect?(name)
+      key = name.to_s
+      return @base.side_effect?(key) if code_tool?(key)
+
+      entry = dynamic.find { |e| e.name == key }
+      entry ? !!entry.metadata[:side_effect] : false
+    end
+
+    # Atomic swap of the dynamic index (after writing/removing a data-tool).
+    def reload
+      @dynamic = build_dynamic
+      self
+    end
+
+    # Is it a CODE tool (base)? Used by the authoring Command's validation.
+    def code_tool?(name) = @base.names.include?(name.to_s)
+
+    private
+
+    def dynamic
+      @dynamic ||= build_dynamic
+    end
+
+    def build_dynamic
+      @tool_store.all_raw.filter_map { |raw| entry_for(raw) }
+    end
+
+    def entry_for(raw)
+      definition = Insika::ToolDefinition.from_h(raw)
+      Insika::Registry::Entry.new(
+        name: definition.name, plugin: "data-tools",
+        metadata: { optional: false, side_effect: definition.side_effect,
+                    group: definition.group, tags: definition.tags },
+        factory: -> { build_tool(definition) }
+      )
+    rescue Insika::ValidationError => e
+      warn "[overlay-tools] invalid definition ignored: #{e.message}"
+      nil
+    end
+
+    # Lazy require: DataDefinedTool inherits from RubyLLM::Tool (pulls in the gem) -> kept
+    # out of insika.rb load-time, loaded on the 1st instance (turn time).
+    def build_tool(definition)
+      require_relative "tools/data_defined_tool"
+      Insika::Tools::DataDefinedTool.new(
+        definition: definition, http: @http, egress: @egress,
+        egress_options: @egress_options, event_stream: @event_stream
+      )
+    end
+  end
+end

data/lib/insika/pack.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  # Provisioning pack (Phase 6/D4/F6): the PORTABLE form of an agent — a
+  # manifest + the prompt files + the skills + the data-tool defs. It's what
+  # `docs/prompt-base/06` describes as a workspace, here in a value object
+  # consumable by the PackImporter (which emits the authoring Commands). GENERIC
+  # per project (NF1): the engine doesn't know achei-b2b — the pack is the contract.
+  #
+  #   config: Hash — manifest (AgentProfile.build attrs: id/model/provider/
+  #           limits/metadata/tools_deferred/…). `id`/`model` required there.
+  #   files:  { "IDENTITY.md" => "<content>", ... } — prompt files (become
+  #           prompt_files via write_agent_file). File name = key.
+  #   skills: { "escalation-to-human" => "<SKILL.md>", ... } — 1 per skill.
+  #   tools:  [ { ToolDefinition hash }, ... ] — the pack's data-tool defs.
+  #
+  # Two sources: `from_h` (GatewayClient JSON — provisioning API, task 8) and
+  # `from_dir` (a folder on disk per docs/prompt-base/06 — authoring/CLI).
+  Pack = Data.define(:config, :files, :skills, :tools) do
+    # Raw Hash (string|symbol keys) -> Pack. Tolerates both key conventions
+    # (the JSON wire may arrive symbolized or not).
+    def self.from_h(hash)
+      h = hash || {}
+      new(
+        config: symbolize(dig(h, :config) || {}),
+        files: text_values!(stringify_keys(dig(h, :files) || {}), "files"),
+        skills: text_values!(stringify_keys(dig(h, :skills) || {}), "skills"),
+        tools: Array(dig(h, :tools))
+      )
+    end
+
+    # A pack's files and skills are NAME => MARKDOWN. Only the keys used to be
+    # normalized, so `{"files": {"AGENTS.md": {"content": "…"}}}` — the shape anyone
+    # writes first — was accepted and reached the store as Ruby's #inspect of the
+    # object. Refuse at the front door, where the name of the offending file is still
+    # in hand.
+    def self.text_values!(hash, field)
+      hash.each do |name, value|
+        next if value.is_a?(String)
+
+        raise Insika::ValidationError,
+              "pack #{field}['#{name}'] must be the file's text, got #{value.class} — " \
+              "a nested object (e.g. {\"content\": …}) is not unwrapped, it is stored verbatim"
+      end
+    end
+    private_class_method :text_values!
+
+    # Folder on disk (docs/prompt-base/06): `agent.config.json` + `*.md` at the
+    # root + `skills/<name>/SKILL.md` + `tools/*.json` (1 ToolDefinition per file).
+    def self.from_dir(path)
+      root = path.to_s
+      config_file = File.join(root, "agent.config.json")
+      raise Insika::ValidationError, "pack missing agent.config.json in #{root}" unless File.exist?(config_file)
+
+      new(
+        config: symbolize(JSON.parse(File.read(config_file, encoding: "UTF-8"))),
+        files: read_md_files(root),
+        skills: read_skills(File.join(root, "skills")),
+        tools: read_tools(File.join(root, "tools"))
+      )
+    end
+
+    def self.dig(hash, key) = hash[key] || hash[key.to_s]
+    private_class_method :dig
+
+    def self.symbolize(hash)
+      (hash || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+    end
+    private_class_method :symbolize
+
+    def self.stringify_keys(hash)
+      (hash || {}).each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+    end
+    private_class_method :stringify_keys
+
+    # `*.md` at the pack ROOT (doesn't descend into skills/). File name = key.
+    def self.read_md_files(root)
+      Dir.glob(File.join(root, "*.md")).sort.each_with_object({}) do |file, acc|
+        acc[File.basename(file)] = File.read(file, encoding: "UTF-8")
+      end
+    end
+    private_class_method :read_md_files
+
+    # `skills/<name>/SKILL.md` -> { "<name>" => "<content>" }.
+    def self.read_skills(dir)
+      Dir.glob(File.join(dir, "*", "SKILL.md")).sort.each_with_object({}) do |file, acc|
+        acc[File.basename(File.dirname(file))] = File.read(file, encoding: "UTF-8")
+      end
+    end
+    private_class_method :read_skills
+
+    # `tools/*.json` -> [ ToolDefinition hash, ... ].
+    def self.read_tools(dir)
+      Dir.glob(File.join(dir, "*.json")).sort.map do |file|
+        JSON.parse(File.read(file, encoding: "UTF-8"))
+      end
+    end
+    private_class_method :read_tools
+  end
+end

data/lib/insika/pack_importer.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Insika
+  # Pack importer (Phase 6/D4/F6, task 7): reads a Pack and emits the ALREADY
+  # existing authoring Commands — create_agent/update_agent + write_agent_file +
+  # write_skill + write_data_tool — making an agent provisionable at runtime from
+  # a standardized pack. It's the piece that achei-b2b's `GatewayClient`/
+  # `ProvisionStore` triggers (via the provisioning API, task 8).
+  #
+  # GENERIC (NF1): nothing here mentions achei-b2b — the pack is the contract. Tool
+  # names come from the PACK, so prompts<->tools stay consistent by construction
+  # (NF2). It doesn't write to the store directly: it only dispatches Commands on
+  # the bus (the same transport discipline) + READS the ProfileSource to decide
+  # create vs update.
+  #
+  # IDEMPOTENT (upsert): re-importing the same pack reconciles — files/skills/
+  # tools rewritten; the allowlists (prompt_files/skills/tools_allow) are
+  # AUTHORITATIVE from the pack, so whatever left the pack leaves the agent
+  # (isolation and no drift). An in-flight turn keeps the profile it captured.
+  class PackImporter
+    def initialize(bus:, profiles:)
+      @bus = bus
+      @profiles = profiles
+    end
+
+    # -> { agent_id:, created:, files: [names], skills: [names], tools: [names] }.
+    # Validation/lookup errors from the Commands (missing id/model, etc.) propagate
+    # (the transport maps them to 422/404).
+    def import(pack)
+      id = presence(pack.config[:id]) ||
+           (raise Insika::ValidationError, "pack missing config.id")
+
+      created = @profiles[id].nil?
+      # create_agent rejects an already-existing id; update_agent requires it to
+      # exist — the choice by presence makes the import an upsert.
+      dispatch(created ? :create_agent : :update_agent, agent_attrs(pack, id))
+
+      pack.files.each { |name, body| dispatch(:write_agent_file, { agent_id: id, file: name, content: body }) }
+      pack.skills.each { |name, body| dispatch(:write_skill, { name: name, content: body }) }
+      pack.tools.each { |defn| dispatch(:write_data_tool, defn) }
+
+      { agent_id: id, created: created,
+        files: pack.files.keys, skills: pack.skills.keys, tools: pack.tools.map { |t| tool_name(t) } }
+    end
+
+    # Removes the agent (delete_agent). Does NOT delete skills/tools/files: they
+    # may be shared and the SkillStore/ToolStore are global — selective removal is
+    # operator work. NotFoundError (missing agent) propagates -> 404.
+    def delete(id)
+      dispatch(:delete_agent, { id: id })
+      { agent_id: id, deleted: true }
+    end
+
+    private
+
+    # AgentProfile.build attrs: the pack manifest + the allowlists derived and
+    # AUTHORITATIVE from the pack. This way the agent only sees the skills/tools of
+    # its OWN pack (per-store isolation) and re-provisioning removes what left.
+    #   - prompt_files = the pack's .md files (write_agent_file also registers;
+    #     union is a no-op). Setting here makes the list authoritative (removes the ones that left).
+    #   - skills = the pack's skills/ dirs (explicit allowlist; [] if none in the
+    #     pack and config didn't declare any — never nil=all, which would leak
+    #     skills from other stores).
+    #   - tools_allow = (config.tools_allow) ∪ (the pack's tool names) — guarantees
+    #     the agent can call its own data-tools (NF2).
+    #   - tools_allow_groups = groups enabled by FLAG in the pack (see
+    #     #enabled_groups) — the per-flag schema CUT (Phase 7, Stage E / D5): only
+    #     the tools of the enabled groups (union with tools_allow) go to the model;
+    #     those of disabled groups are cut BEFORE the turn (resolves the OpenClaw
+    #     tool-call waste, where the flag only exists in Rails).
+    def agent_attrs(pack, id)
+      attrs = pack.config.dup
+      attrs[:id] = id
+      attrs[:prompt_files] = pack.files.keys unless pack.files.empty?
+      attrs[:skills] = pack.skills.keys if pack.skills.any? || pack.config.key?(:skills)
+
+      pack_tools = pack.tools.map { |t| tool_name(t) }
+      allow = Array(pack.config[:tools_allow]).map(&:to_s) | pack_tools
+      attrs[:tools_allow] = allow unless allow.empty? && !pack.config.key?(:tools_allow)
+
+      groups = enabled_groups(pack.config)
+      attrs[:tools_allow_groups] = groups unless groups.nil?
+      attrs
+    end
+
+    # PER-FLAG CUT (Phase 7, Stage E / D5, STATIC pilot): derives the agent's
+    # per-group allowlist from FLAGS declared in the pack config — DATA, never a
+    # core convention (NF1). The engine doesn't know "groceries_v2"/"b2b": the pack
+    # declares which GROUPS are enabled; the flag->group mapping is the
+    # responsibility of provisioning/the pack, not the insika. Two forms (union):
+    #   - `enabled_groups: ["default", "b2b"]`  — explicit list of ON groups.
+    #   - `flags: { "b2b" => true, "natura" => false }` — the flag key IS the group
+    #     name; only the truthy ones enter (the false ones CUT the group).
+    # Neither declared -> nil (no per-group cut; old behavior).
+    # Explicit `[]` (empty enabled_groups, or all flags false) -> no group.
+    def enabled_groups(config)
+      return nil unless config.key?(:enabled_groups) || config.key?(:flags)
+
+      from_list = Array(config[:enabled_groups]).map(&:to_s)
+      from_flags = flag_groups(config[:flags])
+      (from_list | from_flags)
+    end
+
+    # { group => bool } -> [groups with a truthy value]. Accepts string|symbol keys.
+    def flag_groups(flags)
+      return [] unless flags.is_a?(Hash)
+
+      flags.filter_map { |group, on| group.to_s if truthy?(on) }
+    end
+
+    def truthy?(val) = val == true || val.to_s == "true"
+
+    def tool_name(defn) = (defn[:name] || defn["name"]).to_s
+
+    def presence(str) = Insika::Coercion.presence(str)
+
+    def dispatch(type, payload)
+      @bus.dispatch(Insika::Command.build(type, payload, transport: :http))
+    end
+  end
+end

data/lib/insika/pending_action_store.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # Domain store for PENDING approval ACTIONS ("state as a
+  # record, not a flag"). A tool marked `approval` (Policy) creates a
+  # PendingAction and the turn goes to :waiting; the operator resolves it via ApproveAction.
+  # Durable (over an injected Insika::Store): survives a kill -9 — the operator
+  # approves after the reboot, and Recovery rehydrates the task in :waiting.
+  #
+  # Normalizes symbol→string on WRITE (the backend only guarantees round-trip of JSON
+  # types), like the other domain stores.
+  class PendingActionStore
+    include Coercion
+
+    SCOPE = "pending_actions"
+    KEY_PREFIX = "pending:"
+
+    STATUSES = %i[pending approved rejected].freeze
+
+    PendingAction = Data.define(:id, :task_id, :turn, :tool, :args,
+                                :status, :requested_at, :resolved_by, :resolved_at)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> PendingAction (:pending). `args` is the Hash of the tool call's arguments.
+    def create(task_id:, turn:, tool:, args: {}, id: SecureRandom.uuid)
+      record = {
+        "id" => id.to_s,
+        "task_id" => task_id.to_s,
+        "turn" => turn,
+        "tool" => tool.to_s,
+        "args" => deep_stringify(args),
+        "status" => "pending",
+        "requested_at" => timestamp,
+        "resolved_by" => nil,
+        "resolved_at" => nil
+      }
+      @store.set(SCOPE, key_for(id), record)
+      to_pending(record)
+    end
+
+    # -> PendingAction | nil
+    def find(id)
+      record = @store.get(SCOPE, key_for(id))
+      record && to_pending(record)
+    end
+
+    # -> [PendingAction] :pending for the task (recovery/UI). O(n) scan — single-node,
+    # like TaskStore#running_or_interrupted.
+    def open_for(task_id)
+      id = task_id.to_s
+      @store.list(SCOPE, KEY_PREFIX).filter_map do |key|
+        record = @store.get(SCOPE, key)
+        next if record.nil?
+
+        pa = to_pending(record)
+        pa if pa.status == :pending && pa.task_id == id
+      end
+    end
+
+    # -> [PendingAction] every :pending across all tasks — the approvals inbox
+    # (§12 G5, Studio). Single O(n) scan (vs. open_for per task = O(n·m)); the
+    # UI resolves task context afterwards via TaskStore#find.
+    def all_open
+      @store.list(SCOPE, KEY_PREFIX).filter_map do |key|
+        record = @store.get(SCOPE, key)
+        next if record.nil?
+
+        pa = to_pending(record)
+        pa if pa.status == :pending
+      end
+    end
+
+    # -> resolved PendingAction. Only resolves :pending: a double resolution
+    # or an invalid decision -> ValidationError; absent -> NotFoundError.
+    def resolve(id, decision:, operator: nil)
+      target = decision.to_sym
+      unless %i[approved rejected].include?(target)
+        raise Insika::ValidationError, "invalid decision: #{decision} (approved|rejected)"
+      end
+
+      record = @store.get(SCOPE, key_for(id)) ||
+               (raise Insika::NotFoundError, "pending action not found: #{id}")
+      unless record["status"] == "pending"
+        raise Insika::ValidationError, "pending action '#{id}' already resolved (#{record["status"]})"
+      end
+
+      record["status"] = target.to_s
+      record["resolved_by"] = operator&.to_s
+      record["resolved_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_pending(record)
+    end
+
+    private
+
+    def key_for(id) = "#{KEY_PREFIX}#{id}"
+
+    def to_pending(record)
+      PendingAction.new(
+        id: record["id"],
+        task_id: record["task_id"],
+        turn: record["turn"],
+        tool: record["tool"],
+        args: record["args"],
+        status: record["status"].to_sym,
+        requested_at: record["requested_at"],
+        resolved_by: record["resolved_by"],
+        resolved_at: record["resolved_at"]
+      )
+    end
+
+    def timestamp = Time.now.utc.iso8601
+  end
+end