insika 0.0.1 → 0.1.0

data/lib/insika/commands/create_agent.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: creates an agent (AgentProfile) at
+    # RUNTIME and persists it in the ProfileSource (ConfigStore). This is the "everyone creates
+    # their own BIA". Synchronous; does not create a Task. -> AgentProfile (round-tripped from the store).
+    class CreateAgent
+      def initialize(profile_source:, event_stream:)
+        @profile_source = profile_source
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        attrs = AgentPayload.attrs(command.payload)
+        id = AgentPayload.presence(attrs[:id])
+        raise Insika::ValidationError, "id is required" if id.nil?
+        # model is OPTIONAL as of v2 (§10): omitted -> resolves the platform
+        # default_model (Settings) at turn start. An agent with neither its own
+        # model nor a platform default fails clearly at the first turn.
+        raise Insika::ValidationError, "agent '#{id}' already exists" if @profile_source.fetch(id)
+
+        profile = Insika::AgentProfile.build(**attrs)
+        # RFC-0010 §4.4: definition-time cycle + depth check. Only a profile that
+        # introduces edges (non-empty subagents) can create a violation — a
+        # childless agent is always a safe leaf. Raises SubagentError (a
+        # ValidationError) BEFORE persisting, so a bad graph never lands.
+        validate_subagent_graph!(profile)
+        @profile_source.put(profile)
+        emit(:agent_created, id)
+        @profile_source.fetch(id) # returns the persisted profile (symbols already normalized)
+      end
+
+      private
+
+      # Validates the delegation graph with `profile` added to the current set.
+      def validate_subagent_graph!(profile)
+        return if Array(profile.subagents).empty?
+
+        others = @profile_source.all.reject { |p| p.id.to_s == profile.id.to_s }
+        Insika::SubagentGraph.validate!(others + [profile])
+      end
+
+      def emit(type, id)
+        @event_stream.emit(Insika::Event.new(
+                             type: type, data: { agent_id: id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/create_session.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: creates a session and responds synchronously —
+    # does not create a Task. Payload `{ vars: {} }` -> returns Session. `id` optional:
+    # when present, the session is born with that id (correlation by external key —
+    # e.g.: chat.id in the /v1/responses adapter; contextId in A2A). Absent -> uuid.
+    class CreateSession
+      # event_stream: any object with #emit(event) (tests use a spy).
+      def initialize(session_store:, event_stream:)
+        @session_store = session_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        # Accepts a symbol key (internal dispatch) and a string key (transport JSON)
+        # — normalizes at the handler boundary.
+        vars = command.payload[:vars] || command.payload["vars"] || {}
+        raise Insika::ValidationError, "vars must be a Hash" unless vars.is_a?(Hash)
+
+        # Per-chat model pin (v2, §10): `model`/`provider` on the payload become a
+        # reserved, collision-safe slot in vars (never rendered in the prompt — the
+        # Request provider skips "__"-prefixed vars). The ModelResolver reads it as
+        # the highest-precedence layer (Chat > Agent > platform default).
+        vars = apply_model_pin(vars.dup, command.payload)
+
+        id = command.payload[:id] || command.payload["id"]
+        session = id ? @session_store.create(id: id, vars: vars) : @session_store.create(vars: vars)
+        # :session_created is from the closed catalog (origin: CreateSession handler).
+        # meta without task_id/seq (control has no Task); Event#to_h does meta.compact.
+        @event_stream.emit(Insika::Event.new(
+                             type: :session_created,
+                             data: { session_id: session.id },
+                             meta: { session_id: session.id, at: Time.now.utc.iso8601 }
+                           ))
+        session
+      end
+
+      private
+
+      # Reads `model`/`provider`/`thinking` (string|symbol keys) and, when any is
+      # present, writes the reserved vars slot. All must be strings; `thinking` is
+      # the per-chat reasoning override (off/on/low/medium/high) and may be set
+      # WITHOUT a model pin. Absent -> vars unchanged.
+      def apply_model_pin(vars, payload)
+        model = payload[:model] || payload["model"]
+        provider = payload[:provider] || payload["provider"]
+        thinking = payload[:thinking] || payload["thinking"]
+        return vars if model.nil? && provider.nil? && thinking.nil?
+
+        raise Insika::ValidationError, "model must be a String" unless model.nil? || model.is_a?(String)
+        raise Insika::ValidationError, "provider must be a String" unless provider.nil? || provider.is_a?(String)
+        raise Insika::ValidationError, "thinking must be a String" unless thinking.nil? || thinking.is_a?(String)
+
+        pin = {}
+        pin["model"] = model if model
+        pin["provider"] = provider if provider
+        pin["thinking"] = thinking if thinking
+        vars[Insika::ModelResolver::SESSION_SLOT] = pin
+        vars
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_agent.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes an agent. -> the removed AgentProfile
+    # (so the transport can confirm what disappeared). Turns ALREADY in progress
+    # that captured the profile keep going until they finish (the ProfileSource only affects
+    # new dispatches).
+    class DeleteAgent
+      def initialize(profile_source:, event_stream:)
+        @profile_source = profile_source
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        id = AgentPayload.presence(AgentPayload.symbolize(command.payload)[:id])
+        raise Insika::ValidationError, "id is required" if id.nil?
+
+        removed = @profile_source.fetch(id) ||
+                  (raise Insika::NotFoundError, "agent '#{id}' not found")
+
+        @profile_source.delete(id)
+        @event_stream.emit(Insika::Event.new(
+                             type: :agent_deleted, data: { agent_id: id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        removed
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_agent_file.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes a prompt file from an agent's
+    # workspace. Nonexistent -> NotFoundError. -> { agent_id, file }.
+    class DeleteAgentFile
+      def initialize(profile_source:, agent_file_store:, event_stream:)
+        @profile_source = profile_source
+        @agent_files = agent_file_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        agent_id = AgentPayload.presence(p[:agent_id])
+        file = AgentPayload.presence(p[:file])
+        raise Insika::ValidationError, "agent_id is required" if agent_id.nil?
+        raise Insika::ValidationError, "file is required" if file.nil?
+
+        unless @agent_files.delete(agent_id, file)
+          raise Insika::NotFoundError, "file '#{file}' not found for agent '#{agent_id}'"
+        end
+
+        unregister_prompt_file(agent_id, file)
+        @event_stream.emit(Insika::Event.new(
+                             type: :agent_file_deleted, data: { agent_id: agent_id, file: file },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { agent_id: agent_id, file: file }
+      end
+
+      private
+
+      # Removing the file also drops it from prompt_files (the inverse operation of
+      # WriteAgentFile) — the Command's job, not the dispatcher's.
+      def unregister_prompt_file(agent_id, file)
+        profile = @profile_source.fetch(agent_id)
+        return unless profile
+
+        files = Array(profile.prompt_files).map(&:to_s)
+        return unless files.include?(file)
+
+        @profile_source.put(Insika::AgentProfile.build(**profile.to_h.merge(prompt_files: files - [file])))
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_data_tool.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Removes a data tool from the ToolStore and reloads overlay + catalog.
+    # 404 if it did not exist. -> { name }.
+    class DeleteDataTool
+      def initialize(tool_store:, registry:, tool_catalog:, event_stream:)
+        @tool_store = tool_store
+        @registry = registry
+        @tool_catalog = tool_catalog
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        name = AgentPayload.presence(p[:name])
+        raise Insika::ValidationError, "name is required" if name.nil?
+        raise Insika::NotFoundError, "tool '#{name}' not found" unless @tool_store.delete(name)
+
+        @registry.reload
+        @tool_catalog.reload
+        @event_stream.emit(Insika::Event.new(
+                             type: :data_tool_deleted, data: { name: name },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { name: name }
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_llm_provider.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes an LLM provider from the
+    # LLMProviderStore. Idempotent (`existed: false` if there was none). UNDOES the
+    # config in RubyLLM at runtime (§9.5): when the provider existed, calls
+    # `configurator.unapply(api)` clearing the global key/base — without a restart. A provider
+    # that RubyLLM does not recognize degrades gracefully (unapply: false, nothing to
+    # undo). -> { existed: bool }.
+    class DeleteLLMProvider
+      def initialize(provider_store:, configurator:, event_stream:)
+        @provider_store = provider_store
+        @configurator = configurator
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        api = AgentPayload.presence(p[:api])
+        raise Insika::ValidationError, "api is required" if api.nil?
+
+        existed = @provider_store.delete(api)
+        @configurator.unapply(api) if existed
+        @event_stream.emit(Insika::Event.new(
+                             type: :llm_provider_deleted,
+                             data: { api: api, existed: existed },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { existed: existed }
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_mcp.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes an MCP instance from the
+    # McpStore. Idempotent (`existed: false` if there was none). -> { existed: bool }.
+    class DeleteMcp
+      def initialize(mcp_store:, event_stream:)
+        @mcp_store = mcp_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        name = AgentPayload.presence(p[:name])
+        raise Insika::ValidationError, "name is required" if name.nil?
+
+        existed = @mcp_store.delete(name)
+        @event_stream.emit(Insika::Event.new(
+                             type: :mcp_deleted,
+                             data: { name: name, existed: existed },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { existed: existed }
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_system_file.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes a global system file
+    # from the SystemFileStore. Idempotent (`existed: false`). -> { existed: bool }.
+    class DeleteSystemFile
+      def initialize(system_file_store:, event_stream:)
+        @system_files = system_file_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        file = AgentPayload.presence(p[:file])
+        raise Insika::ValidationError, "file is required" if file.nil?
+
+        existed = @system_files.delete(file)
+        @event_stream.emit(Insika::Event.new(
+                             type: :system_file_deleted, data: { file: file, existed: existed },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { existed: existed }
+      end
+    end
+  end
+end

data/lib/insika/commands/gate_refinement.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command (RFC-0013 phase C): takes a CANDIDATE for a completed
+    # refinement run, validates it against the agent's write allowlist, and scores it
+    # by actually running it — clone the agent, apply the edits to the clone, replay
+    # the golden set, compare to the accepted baseline (§3.5).
+    #
+    # Synchronous like `run_refinement`, and for the same reason: it is operator-paced
+    # work with a human waiting on the answer. It is NOT cheap — the replay is a real
+    # conversation per golden case — so it is fired deliberately, never on a timer
+    # (D8: the engine has no scheduler and this RFC does not add one).
+    #
+    # Payload:
+    #   run_id     (required) a run in :completed — the evidence the candidate answers
+    #   candidate  { proposer?, rationale?, edits: [ {file, op, anchor?, before, after,
+    #              addresses?} ] } — or omit it and pass `propose: true` to have the
+    #              configured model(s) write one from the run's findings (§3.4).
+    #   propose    truthy — write the candidate with the agent's proposer PANEL.
+    #   tolerance  Float — overrides the configured judge-score tolerance for this gate
+    #
+    # -> the Run, now :awaiting_approval (gate passed), :applied (`mode: auto_apply`
+    # and the candidate cleared the extra bar) or :rejected (the gate said no).
+    #
+    # **`propose: true` is required rather than inferred from a missing candidate.**
+    # Both a proposal and a gate cost real provider money, and a caller who simply
+    # forgot the candidate should get an error, not a bill.
+    #
+    # Two refusals happen BEFORE anything is cloned, because both mean the operator
+    # has not actually enabled this: an agent still in `mode: report` (§3.8 — writing
+    # is opt-in and an absent config is report-only), and a candidate whose every edit
+    # was dropped (stale, off-allowlist, over budget). Neither is worth a provider bill.
+    #
+    # Phase D (§3.9) makes the proposal a PANEL and the run's spend a BUDGET. The
+    # command's shape does not change: N models write N candidates, the gate scores
+    # each, and the best survivor is the one proposal a human is shown. A deployment
+    # with one proposer and no budget behaves exactly as phase C did.
+    class GateRefinement
+      WRITE_MODES = %w[propose auto_apply].freeze
+
+      # An unattended write is held to a SMALLER bar than an approved one: one edit,
+      # by default. `auto_apply` exists so a well-understood, well-golden'd agent can
+      # fix a typo'd instruction overnight — not so it can rewrite three files while
+      # nobody is looking. The operator raises it deliberately.
+      DEFAULT_AUTO_APPLY_MAX_EDITS = 1
+
+      # proposer_factory: ->(refinement_config) { [Refinement::Proposer] | Proposer | nil }.
+      # Optional — a deployment with none can still gate a candidate that arrives from
+      # the API, which is exactly what phase C shipped before the proposer existed.
+      # resolver: the :resolve_refinement handler, used ONLY for `mode: auto_apply`.
+      # Reusing it rather than writing files here is what keeps auto-apply honest: it
+      # goes through the same staleness re-check, the same versioned write and the
+      # same `:refinement_applied` event a human approval does.
+      def initialize(profiles:, refinement_store:, agent_file_store:, gate:, event_stream:,
+                     proposer_factory: nil, resolver: nil)
+        @profiles = ProfileSource.coerce(profiles)
+        @runs = refinement_store
+        @agent_files = agent_file_store
+        @gate = gate
+        @event_stream = event_stream
+        @proposer_factory = proposer_factory
+        @resolver = resolver
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        run_id = AgentPayload.presence(p[:run_id])
+        raise Insika::ValidationError, "run_id is required" if run_id.nil?
+
+        run = @runs.find(run_id) || (raise Insika::NotFoundError, "refinement run not found: #{run_id}")
+        profile = @profiles[run.agent_id] ||
+                  (raise Insika::NotFoundError, "agent '#{run.agent_id}' not configured")
+        config = refinement_config(profile)
+        require_write_mode!(config, run.agent_id)
+        require_completed!(run)
+
+        result = run_panel(run, config, p)
+        report = (result.winner || Refinement::Panel.best_refusal(result.entries)).report
+
+        gated = @runs.gated(run.id, report: report, panel: result.entries,
+                                    cost: result.budget)
+        emit(:refinement_gated, gated, passed: report.passed, reason: report.reason,
+                                       cases: report.cases, passed_cases: report.passed_cases,
+                                       regressions: report.regressions.size,
+                                       candidates: result.entries.size,
+                                       tokens: result.budget.to_h["spent"])
+        auto_apply(gated, config, report) || gated
+      end
+
+      private
+
+      # Propose (a panel, or the caller's own candidate), build, gate, rank. The
+      # `gating` status and the `:refinement_proposed` event land BEFORE any scoring,
+      # because the scoring is minutes of real replay and a run that says nothing
+      # until it finishes looks hung.
+      def run_panel(run, config, payload)
+        panel = Refinement::Panel.new(
+          gate: @gate, proposers: proposers_for(run, config, payload),
+          budget: Refinement::Budget.new(tokens: budget_tokens(config))
+        )
+
+        panel.run(agent_id: run.agent_id, run_id: run.id, findings: run.findings,
+                  files: writable_files(run.agent_id, config),
+                  allowlist: allowlist!(run.agent_id, config),
+                  contents: current_files(run.agent_id), limits: config,
+                  raw: payload[:candidate], tolerance: payload[:tolerance]) do |entries|
+          @runs.gating(run.id, candidates: entries)
+          emit(:refinement_proposed, run, candidates: entries.size,
+                                          proposers: entries.flat_map(&:proposers).uniq,
+                                          edits: entries.sum { |e| e.candidate.edits.size })
+        end
+      end
+
+      def budget_tokens(config)
+        budget = config["budget"]
+        budget.is_a?(Hash) ? budget["tokens"] : nil
+      end
+
+      def refinement_config(profile)
+        raw = profile.respond_to?(:refinement) ? profile.refinement : nil
+        raw.is_a?(Hash) ? Coercion.deep_stringify(raw) : {}
+      end
+
+      # Editing an agent's instructions is opt-in, explicitly, per agent — the whole
+      # point of §3.1 is that the reachable surface is small and declared. An absent
+      # or `report` config is not "not configured yet", it is a NO.
+      def require_write_mode!(config, agent_id)
+        mode = Coercion.presence(config["mode"]) || "report"
+        return if WRITE_MODES.include?(mode)
+
+        raise Insika::ValidationError,
+              "agent '#{agent_id}' is in refinement mode '#{mode}' — set `refinement.mode` to " \
+              "propose (and list the writable files) before gating a candidate"
+      end
+
+      # `RefinementStore#gating` refuses a run that is not :completed — but it is
+      # called AFTER the proposal, so the refusal used to arrive with the provider
+      # bill already paid. Found live: a run_id pointing at an :awaiting_approval run
+      # burned a minute and two model calls to learn the run could not be gated.
+      # Same rule as mode and allowlist: everything the engine can refuse for free
+      # is refused before a model is asked anything.
+      def require_completed!(run)
+        return if run.status == :completed
+
+        raise ArgumentError, "run #{run.id} is #{run.status}, expected completed"
+      end
+
+      # The model(s) write the candidates (§3.4/§3.9). Each is shown the run's findings
+      # and the CURRENT content of the allowlisted files only — the same allowlist the
+      # builder then enforces, so a proposal cannot even name a file it may not touch.
+      #
+      # A caller who supplied their own candidate needs no proposer at all; that path
+      # is what an API client and the phase-C Studio button use.
+      def proposers_for(run, config, payload)
+        return [] if payload[:candidate]
+
+        unless Insika::EnvSchema.truthy?(payload[:propose])
+          raise Insika::ValidationError,
+                "candidate is required (or pass propose: true to have the configured model write one)"
+        end
+
+        panel = Array(@proposer_factory&.call(config))
+        if panel.empty?
+          raise Insika::ValidationError,
+                "no proposer is configured for '#{run.agent_id}' — set `refinement.proposers` " \
+                "(or `refinement.proposer`, or a platform utility_model) to a model that can " \
+                "write the candidate"
+        end
+
+        panel
+      end
+
+      # The allowlist ∩ what the agent actually has. A configured file the agent never
+      # got is not shown and not editable — the builder would drop the edit anyway
+      # ("does not exist for this agent"), and paying a model to write one is waste.
+      def writable_files(agent_id, config)
+        allow = allowlist!(agent_id, config)
+        current_files(agent_id).select { |name, _| allow.include?(name) }
+      end
+
+      # Checked before the proposer runs as well as before the gate: an empty
+      # allowlist is `mode: propose` with nothing switched on, and it is the one
+      # refusal that must land before a provider call, not after it.
+      def allowlist!(agent_id, config)
+        allow = Array(config["files"]).map(&:to_s)
+        if allow.empty?
+          raise Insika::ValidationError,
+                "agent '#{agent_id}' has an empty refinement.files allowlist — nothing is writable"
+        end
+
+        allow
+      end
+
+      # `mode: auto_apply` (§3.6, D2) — the ONE path where a prompt changes with no
+      # human in the loop. Off by default and deliberately narrow: it needs the mode,
+      # a gate PASS with zero regressions, and a diff under `auto_apply_max_edits`.
+      # Everything else parks at :awaiting_approval, which is the product.
+      #
+      # A candidate that passed but is too large is NOT rejected — it waits for a
+      # person. "Too big to apply unattended" and "wrong" are different verdicts, and
+      # collapsing them would throw away a proposal the gate already paid to score.
+      #
+      # Without a wired resolver this returns nil and the run stays awaiting approval:
+      # a deployment that cannot apply must not record that it did.
+      # -> the applied Run, or nil when nothing was applied.
+      def auto_apply(run, config, report)
+        return nil unless Coercion.presence(config["mode"]) == "auto_apply"
+        return nil unless run.awaiting_approval? && report.passed && report.regressions.empty?
+        return nil if @resolver.nil?
+
+        max = (config["auto_apply_max_edits"] || DEFAULT_AUTO_APPLY_MAX_EDITS).to_i
+        edits = run.edits.size
+        if edits > max
+          emit(:refinement_auto_apply_skipped, run, edits: edits, max_edits: max)
+          return nil
+        end
+
+        @resolver.call(Insika::Command.build(:resolve_refinement,
+                                             { run_id: run.id, decision: "approved",
+                                               operator: "auto_apply",
+                                               note: "auto_apply: gate passed #{report.passed_cases}/" \
+                                                     "#{report.cases} with no regression" }))
+      end
+
+      def current_files(agent_id)
+        @agent_files.list(agent_id).each_with_object({}) do |name, acc|
+          acc[name] = @agent_files.read(agent_id, name).to_s
+        end
+      end
+
+      # Counts and ids only, never file content: these events reach the operator
+      # stream and the same rule the findings follow applies here (§5).
+      def emit(type, run, **data)
+        @event_stream.emit(Insika::Event.new(
+                             type: type,
+                             data: { agent: run.agent_id, run_id: run.id, status: run.status.to_s, **data },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/import_mcp_tools.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: LIVE MCP ingestion (Phase 7, Step E). Receives the NAME of
+    # an MCP instance, delegates to McpToolIngestor (discovers via an injectable client
+    # -> builds the manifest -> reuses :import_tools: batch upsert + hot reload)
+    # and returns the per-tool report in the shape of :import_tools, plus
+    # `instance:`. Idempotent (re-ingesting reconciles). A per-tool failure is isolated
+    # in `errors[]` (R4); an absent/disabled/url-less instance raises.
+    #   -> { instance, version, created: [names], updated: [names], errors: [{tool,error}] }
+    class ImportMcpTools
+      def initialize(ingestor:, event_stream:)
+        @ingestor = ingestor
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = symbolize(command.payload)
+        name = Insika::Coercion.presence(p[:name]) ||
+               (raise Insika::ValidationError, "import_mcp_tools: 'name' (MCP instance) is required")
+
+        report = @ingestor.ingest(name)
+        emit(report)
+        report
+      end
+
+      private
+
+      # Emits only COUNTS + the instance name (never headers/env/secrets): 0 leakage.
+      def emit(report)
+        @event_stream.emit(Insika::Event.new(
+                             type: :mcp_tools_imported,
+                             data: { instance: report[:instance],
+                                     created: report[:created].size, updated: report[:updated].size,
+                                     errors: report[:errors].size },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+
+      def symbolize(payload)
+        (payload || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+    end
+  end
+end