insika 0.2.0 → 0.7.0

data/lib/insika/channels/relay.rb

@@ -3,6 +3,7 @@
 require "digest"
 require "json"
 require "openssl"
+require "time"
 require "uri"
 
 module Insika
@@ -33,12 +34,25 @@ module Insika
       DEFAULT_ID = "relay"
       DEFAULT_TIMEOUT = 10
 
+      # how the outbox flushes for THIS channel. `:at_end` (the
+      # default) is one POST with the whole answer, byte-identical to today;
+      # `:progressive` lets ChannelDelivery split the answer into balloons and
+      # POST them in order (the channel still only translates — it does not know
+      # what a balloon is).
+      POLICIES = %i[at_end progressive].freeze
+
       attr_reader :id
 
       # The bundled relay as an operator configures it: three env vars, of which the
       # token is the SWITCH — no token, no channel, so there is no way to end up with
       # this route mounted and open. -> Relay | nil.
       #
+      # `INSIKA_RELAY_SHADOW` (truthy) is the shadow switch: the turn
+      # runs end to end and the reply is recorded, never delivered.
+      #
+      # `INSIKA_RELAY_DELIVERY` ("progressive" | "at_end") is how the outbox
+      # flushes. Unset = :at_end.
+      #
       # Shared by every composition root on purpose: the DSL front door has to reach
       # the same feature as `config.ru`, or the docs are true of only one of them.
       def self.from_env(env = ENV, http: nil, allow_http: false, allow_private: false)
@@ -48,6 +62,8 @@ module Insika
         new(inbound_token: token,
             deliver_url: Insika::EnvSchema.read("INSIKA_RELAY_DELIVER_URL", env),
             deliver_token: Insika::EnvSchema.read("INSIKA_RELAY_DELIVER_TOKEN", env),
+            shadow: Insika::EnvSchema.truthy?(Insika::EnvSchema.read("INSIKA_RELAY_SHADOW", env)),
+            delivery: policy!(Insika::EnvSchema.read("INSIKA_RELAY_DELIVERY", env)),
             http: http, allow_http: allow_http, allow_private: allow_private)
       end
 
@@ -59,9 +75,14 @@ module Insika
       #                 reply and the delivery fails loudly instead of silently).
       # deliver_token:  Bearer we send THEM. Optional: a consumer on a private
       #                 network may authenticate us another way.
+      # shadow: The turn runs, the reply is recorded and never
+      #                 sent. Fail-closed by construction: everything downstream
+      #                 duck-types `shadow?`, so a channel that does not answer it
+      #                 is a normal channel.
+      # delivery: How the outbox flushes (:at_end | :progressive).
       def initialize(inbound_token:, deliver_url:, deliver_token: nil, http: nil,
                      id: DEFAULT_ID, allow_http: false, allow_private: false,
-                     timeout: DEFAULT_TIMEOUT)
+                     timeout: DEFAULT_TIMEOUT, shadow: false, delivery: :at_end)
         @id = id.to_s
         @inbound_token = inbound_token.to_s
         @deliver_url = deliver_url.to_s
@@ -70,10 +91,30 @@ module Insika
         @allow_http = allow_http
         @allow_private = allow_private
         @timeout = timeout
+        @shadow = shadow
+        @delivery = self.class.policy!(delivery)
+      end
+
+      def shadow? = @shadow
+
+      def delivery = @delivery
+      def progressive? = @delivery == :progressive
+
+      # "progressive" | "at_end" | blank/unset (= :at_end). An unknown value is
+      # a config error at BOOT — the consumer would silently miss every
+      # progressive turn, so it is refused where the operator is.
+      def self.policy!(value)
+        return :at_end if Insika::Coercion.blank?(value)
+
+        name = value.to_s.strip.downcase.to_sym
+        return name if POLICIES.include?(name)
+
+        raise Insika::ConfigError,
+              "unknown relay delivery: #{value.inspect} (expected #{POLICIES.join(', ')})"
       end
 
       # -> :ok | :unauthorized | :disabled. A SYMBOL and not a Rack triple (the
-      # RFC sketched one): a status code is the transport's vocabulary, and keeping
+      # the design sketched one): a status code is the transport's vocabulary, and keeping
       # it out of here is what lets this class be tested without Rack and read
       # without knowing HTTP.
       def authenticate(req)
@@ -91,19 +132,25 @@ module Insika
       #   { "agent": "support", "external_id": "5511999998888",
       #     "event_id": "wamid.HBg…", "message": "queria saber do pedido",
       #     "vars": { … } }
+      #
+      # In SHADOW mode `event_id` is REQUIRED: it is the correlation key both
+      # halves of the pair are built from, and a mirror that cannot supply a
+      # stable id cannot be paired.
       def parse(_req, body:)
         body = body.is_a?(Hash) ? body : {}
         agent = string(body["agent"])
         external_id = string(body["external_id"])
         message = string(body["message"])
+        event_id = presence(body["event_id"])
 
         raise Insika::ValidationError, "agent is required" if agent.empty?
         raise Insika::ValidationError, "external_id is required" if external_id.empty?
         raise Insika::ValidationError, "message is required" if message.strip.empty?
+        raise Insika::ValidationError, "event_id is required in shadow mode" if @shadow && event_id.nil?
 
         vars = body["vars"].is_a?(Hash) ? body["vars"] : {}
         { agent: agent, external_id: external_id, message: message,
-          event_id: presence(body["event_id"]), vars: vars }
+          event_id: event_id, vars: vars, incumbent_reply: presence(body["incumbent_reply"]) }
       end
 
       # the engine namespaces the platform's conversation key, so a
@@ -127,6 +174,8 @@ module Insika
       # consumer that receives the same delivery twice (we retried after a timeout
       # that actually landed) can drop the second one.
       def deliver(payload, to:, delivery_id: nil)
+        raise Insika::DeliveryError, "relay '#{@id}' is in shadow mode and must never deliver" if @shadow
+
         raise Insika::DeliveryError, "relay deliver_url is not configured" if @deliver_url.empty?
 
         if (reason = egress_violation)
@@ -143,8 +192,33 @@ module Insika
         raise Insika::DeliveryError, "#{e.class}: #{e.message}"
       end
 
+      # The reply, as recorded by the mirror. Follows the
+      # same strictness as `parse`; `at` is optional (nil = now).
+      def parse_shadow_reply(_req, body:)
+        body = body.is_a?(Hash) ? body : {}
+        external_id = string(body["external_id"])
+        event_id = presence(body["event_id"])
+        reply = string(body["reply"])
+
+        raise Insika::ValidationError, "external_id is required" if external_id.empty?
+        raise Insika::ValidationError, "event_id is required" if event_id.nil?
+        raise Insika::ValidationError, "reply is required" if reply.strip.empty?
+
+        at = presence(body["at"])
+        raise Insika::ValidationError, "at must be an ISO8601 timestamp" if at && !parseable_time?(at)
+
+        { external_id: external_id, event_id: event_id, reply: reply, at: at }
+      end
+
       private
 
+      def parseable_time?(value)
+        Time.iso8601(value)
+        true
+      rescue ArgumentError
+        false
+      end
+
       # Resolved on EVERY call, not once at boot: a hostname that answered a public
       # address yesterday can answer 169.254.169.254 today, and this POST carries
       # the customer's conversation.

data/lib/insika/channels/web.rb

@@ -7,7 +7,7 @@ require "securerandom"
 module Insika
   module Channels
     # The web widget — the FIRST Shape A channel, and the adoption
-    # claim behind the whole RFC: an adopter pastes one tag into their site and has
+    # claim behind the whole design: an adopter pastes one tag into their site and has
     # a working agent, with no backend of their own and no build step.
     #
     #   <script src="https://agents.example.com/channels/web/asset/widget.js"
@@ -50,7 +50,7 @@ module Insika
       # never reach a browser that already has it. Short max-age + an ETag instead:
       # the common case is a 304 with no body, and an upgrade lands within minutes.
       # (A deliberate narrowing of's "long-cache versioned URL": the install
-      # snippet in the RFC has no version in it, so there is nothing to bust.)
+      # snippet has no version in it, so there is nothing to bust.)
       ASSET_CACHE_CONTROL = "public, max-age=300"
 
       attr_reader :id

data/lib/insika/chat_builder.rb

@@ -14,7 +14,8 @@ module Insika
   class ChatBuilder
     def initialize(tool_registry:, skill_catalog:, checkpoint_store:, event_stream:,
                    hooks:, tool_catalog: nil, memory_store: nil, subagent_runner: nil,
-                   tool_trace_store: nil)
+                   tool_trace_store: nil, media_runner: nil, session_store: nil,
+                   contact_store: nil, followup_store: nil, knowledge_store: nil)
       @tool_registry = tool_registry
       @skill_catalog = skill_catalog
       @checkpoint_store = checkpoint_store
@@ -22,12 +23,29 @@ module Insika
       @hooks = hooks
       @tool_catalog = tool_catalog
       @memory_store = memory_store
+      # load_knowledge is the knowledge-read system tool — wired only with
+      # @knowledge_store present AND profile.knowledge["retrieve"] (a double
+      # gate, like remember). nil = never wired (parity).
+      @knowledge_store = knowledge_store
       # only to trace load_skill, which is not enveloped — nil = no trace (parity).
       @tool_trace_store = tool_trace_store
       # the object exposing #run_subagent (the Executor). nil = the
       # spawn_subagent system tool is never wired (parity for a builder used
       # without delegation, e.g. some unit stubs).
       @subagent_runner = subagent_runner
+      # the Executor as the generate_image/tts runner (seams + usage
+      # accounting). nil = the media tools are never wired (parity for stubs).
+      @media_runner = media_runner
+      # update_briefing / set_next_step are the briefing-write system
+      # tools — wired only with @session_store present AND profile.briefing_fields
+      # non-empty (double gate, like remember). nil = never wired (parity for a
+      # builder used without session persistence, e.g. some unit stubs).
+      @session_store = session_store
+      # the schedule/cancel_followup system tools — wired only
+      # with BOTH stores present AND a parsed follow-up policy on the profile
+      # (double gate, like remember). nil = never wired (parity).
+      @contact_store = contact_store
+      @followup_store = followup_store
     end
 
     # Configures an already-created chat with the context (stage 2) and the
@@ -90,6 +108,31 @@ module Insika
                                      event_stream: @event_stream, state: state)
       end
 
+      # load_knowledge is a system default (outside the allowlist), like
+      # load_skill — wired only with @knowledge_store present AND the
+      # profile's opt-in (double gate, like remember). Reads the same
+      # (agent, tenant) scope the Knowledge context provider searches.
+      if @knowledge_store && Coercion.truthy?(state.profile.knowledge&.dig("retrieve"))
+        tools << Tools::LoadKnowledge.new(@knowledge_store, state.profile.id, tenant: state.tenant,
+                                          trace_recorder: @tool_trace_store, state: state)
+      end
+
+      # update_briefing / set_next_step are the briefing-write system tools
+      #  — wired only with @session_store present AND
+      # profile.briefing_fields non-empty (double gate, like remember). Never
+      # enveloped: deterministic in-process writes.
+      fields = if state.profile.respond_to?(:briefing_fields)
+                 Array(state.profile.briefing_fields).map(&:to_s)
+               else
+                 []
+               end
+      if @session_store && !fields.empty?
+        tools << Tools::UpdateBriefing.new(session_store: @session_store, fields: fields,
+                                           event_stream: @event_stream, state: state)
+        tools << Tools::UpdateBriefing::SetNextStep.new(session_store: @session_store,
+                                                        event_stream: @event_stream, state: state)
+      end
+
       # signal_stuck is the "I cannot proceed" system tool (WS5) — wired only
       # when the agent opted in (`profile.stuck_signal`), never enveloped. It is a
       # deterministic signal; the consumer decides what "stuck" means. Defensive
@@ -98,6 +141,33 @@ module Insika
         tools << Tools::StuckSignal.new(state: state)
       end
 
+      # schedule/cancel_followup are the follow-up system tools  —
+      # wired only with BOTH stores present AND a parsed follow-up policy on
+      # the profile (double gate, like remember). Never enveloped: the store
+      # writes are deterministic. The tools stay OUT of the allowlist — they
+      # are data-driven per agent, not admittable (prompts/memory/stuck_signal
+      # are the precedent).
+      if @contact_store && @followup_store && followup_policy(state)
+        tools << Tools::ScheduleFollowup.new(contact_store: @contact_store,
+                                             followup_store: @followup_store,
+                                             state: state,
+                                             event_stream: @event_stream)
+        tools << Tools::CancelFollowup.new(followup_store: @followup_store,
+                                           state: state,
+                                           event_stream: @event_stream)
+      end
+
+      # generate_image / tts are the generated-media system tools (WS9, saída)
+      # — wired only when BOTH gates pass, never enveloped: the AGENT opted in
+      # (`profile.outputs` — the per-kind generator config) AND the CHANNEL
+      # declared it can receive the media (state.channel_capabilities, from the
+      # request's `channel.capabilities`). The "abstraction admits only what
+      # leaks" rule, C4: a channel that never declared image_output cannot get
+      # a generated image; a profile without `outputs` never generates. The
+      # runner is the Executor (seams + usage accounting); nil = no media
+      # output at all (parity for a stub builder).
+      output_media_tools(state).each { |tool| tools << tool } if @media_runner
+
       # spawn_subagent is the delegation system tool — wired only with a
       # runner present AND profile.subagents non-empty (a double gate, like
       # remember). Never enveloped: in the synchronous mode the child lives in the
@@ -139,6 +209,32 @@ module Insika
       names - eager
     end
 
+    # the follow-up tools' gate — a PARSED policy on the profile.
+    # A malformed declaration reads as "no policy" (the firer blocks it, the
+    # doctor reports it; the tools are simply not offered).
+    def followup_policy(state)
+      followup = state.profile.respond_to?(:followup) ? state.profile.followup : nil
+      followup && Insika::FollowupPolicy.parse(followup)
+    end
+
+    # WS9 (saída): the media-output tools this turn may carry, per the double
+    # gate (profile outputs ∩ channel capabilities). [] = none. Defensive reads
+    # throughout — a minimal profile/state stub is "off", which is the safe
+    # parity reading.
+    def output_media_tools(state)
+      outputs = state.profile.respond_to?(:outputs) ? state.profile.outputs : nil
+      return [] unless outputs.is_a?(Hash)
+      return [] unless state.respond_to?(:channel_capabilities)
+
+      caps = Array(state.channel_capabilities).map(&:to_s)
+      image_cfg = outputs["image"]
+      tts_cfg = outputs["tts"]
+      [
+        (Tools::GenerateImage.new(runner: @media_runner, config: image_cfg, state: state) if image_cfg.is_a?(Hash) && caps.include?("image_output")),
+        (Tools::Tts.new(runner: @media_runner, config: tts_cfg, state: state) if tts_cfg.is_a?(Hash) && caps.include?("audio_output"))
+      ].compact
+    end
+
     # The turn's effective tool concurrency (nil = serial), plus the ONE thing the
     # gate owes the operator: when the profile asked for parallel tool calls and
     # this turn silently cannot have them (an approval-required tool would
@@ -279,9 +375,16 @@ module Insika
         # under concurrency `after_tool_result` labelled every result with whichever
         # call started last.
         state.current_tool_name = tool_call.name.to_s
-        if state.current_tool_name == "load_skill"
+        case state.current_tool_name
+        when "load_skill"
           args = tool_call.arguments || {}
           emit.call(:skill_activated, { name: args["name"] || args[:name] })
+        when "load_knowledge"
+          # The adoption risk is the model never calling this tool, not what
+          # it injects — so the metric here is retrieval CALLS, tracked at
+          # the same point :skill_activated is.
+          args = tool_call.arguments || {}
+          emit.call(:knowledge_retrieved, { name: args["name"] || args[:name], agent: state.profile.id })
         else
           emit.call(:tool_call, { name: tool_call.name, arguments: tool_call.arguments })
         end

data/lib/insika/checkpoint_store.rb

@@ -109,6 +109,22 @@ module Insika
       nil
     end
 
+    # Deletes EVERY checkpoint + side-effect record of the task (WS8 retention:
+    # a purged task's durability trail goes with it — no orphaned keys).
+    # -> count of records removed.
+    def purge(task_id)
+      removed = 0
+      checkpoint_turns(task_id).each do |n|
+        @store.delete(SCOPE, checkpoint_key(task_id, n))
+        removed += 1
+      end
+      sideeffect_turns(task_id).each do |n|
+        @store.delete(SCOPE, sideeffects_key(task_id, n))
+        removed += 1
+      end
+      removed
+    end
+
     private
 
     def checkpoint_key(task_id, turn)

data/lib/insika/commands/agent_payload.rb

@@ -12,10 +12,10 @@ module Insika
       FIELDS = %i[id model provider base_prompt prompt_files tools_allow tools_deny
                   tools_allow_groups skills skills_eager context_providers workflows_allow policies
                   prompt_refs limits approvals_required capabilities subagents tools_deferred
-                  memory prompt_caching tool_output_compression budget reliability alerts
-                  stuck_signal
+                  memory prompt_caching tool_persistence tool_output_compression budget reliability alerts
+                  routes stuck_signal outputs stt_prompt briefing_fields grounding funnel followup
                   params model_policy guardrails refinement capabilities_declared
-                  edge_stream metadata].freeze
+                  edge_stream metadata distill harvest knowledge schedules].freeze
 
       module_function
 

data/lib/insika/commands/backfill_knowledge.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # The recovery path (extraction is best-effort — a crash between a turn's
+    # terminal and the write loses that turn's concepts, not the conversation
+    # nor a previously learned one). Replays one agent's stored sessions
+    # through the SAME `Knowledge::Extractor` the per-turn hook uses.
+    #
+    # Synchronous — the CLI's own path (`insika knowledge:backfill`), same
+    # "no app boot" discipline as RunHarvest/RunDistillation: no task, no
+    # turn, nothing written but the concepts themselves.
+    class BackfillKnowledge
+      DEFAULT_MIN_MESSAGES = 2
+
+      def initialize(profiles:, knowledge_store:, session_store:, task_store:,
+                     settings_store: nil, event_stream:, extractor_factory: nil, consolidator_factory: nil)
+        @profiles = ProfileSource.coerce(profiles)
+        @knowledge_store = knowledge_store
+        @session_store = session_store
+        @task_store = task_store
+        @settings_store = settings_store
+        @extractor_factory = extractor_factory ||
+                             ->(config) { Knowledge::ExtractorFactory.build(config, utility_model: utility_model) }
+        @consolidator_factory = consolidator_factory ||
+                                ->(config) { Knowledge::ConsolidatorFactory.build(config, utility_model: utility_model) }
+        @event_stream = event_stream
+      end
+
+      # payload: { agent:, since?: ISO8601 }
+      # -> { backfilled: true, sessions: N, concepts: N, conflicts: N, dropped: {...} }
+      #  | { backfilled: false, skipped: "disabled|no_model|no_sessions" }
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        agent = AgentPayload.presence(p[:agent])
+        raise Insika::ValidationError, "agent is required" if agent.nil?
+
+        profile = @profiles[agent] || (raise Insika::NotFoundError, "agent '#{agent}' not configured")
+        config = Coercion.deep_stringify(profile.knowledge)
+        return skip("disabled") if config.nil? || !Coercion.truthy?(config["extract"])
+
+        extractor = @extractor_factory.call(config)
+        return skip("no_model") if extractor.nil?
+
+        # Same resolved model as the extractor. nil (unresolvable) is still
+        # meaningful: Knowledge.write_concept's conservative default.
+        consolidator = @consolidator_factory.call(config)
+
+        sessions = resolve_sessions(agent, p)
+        return skip("no_sessions") if sessions.empty?
+
+        concepts = 0
+        conflicts = 0
+        dropped = Hash.new(0)
+        sessions.each do |s|
+          result = extractor.extract(prompt: build_prompt(config, s[:messages]))
+          result[:concepts].each do |c|
+            case write_concept(profile, s[:id], c, consolidator)[:verdict]
+            when :new, :related then concepts += 1
+            when :contradicting then conflicts += 1
+            end
+          end
+          result[:dropped].each { |k, v| dropped[k] += v }
+        end
+
+        emit(:knowledge_backfilled, agent: agent, sessions: sessions.size, concepts: concepts,
+                                    conflicts: conflicts, dropped: dropped.to_h)
+        { backfilled: true, sessions: sessions.size, concepts: concepts, conflicts: conflicts, dropped: dropped.to_h }
+      end
+
+      private
+
+      def skip(reason) = { backfilled: false, skipped: reason }
+
+      # Every task of the agent, distinct session ids, newest first — the
+      # same reading `RunHarvest#window_session_ids` uses, without the
+      # last-N cap (a backfill is meant to be exhaustive over `--since`).
+      def resolve_sessions(agent, p)
+        since = AgentPayload.presence(p[:since])
+        tasks = @task_store.each_id.filter_map { |id| @task_store.find(id) }
+                           .select { |t| task_agent(t) == agent }
+                           .sort_by { |t| [t.created_at.to_s, t.id] }.reverse
+        tasks = tasks.select { |t| t.created_at.to_s >= since.to_s } if since
+
+        seen = {}
+        tasks.filter_map do |t|
+          sid = Coercion.presence(t.session_id)
+          next if sid.nil? || seen[sid]
+
+          seen[sid] = true
+          session = @session_store.find(sid)
+          next unless session && session.messages.size >= DEFAULT_MIN_MESSAGES
+
+          { id: sid.to_s, messages: session.messages }
+        end
+      end
+
+      def task_agent(task)
+        task.command.is_a?(Hash) ? task.command.dig("payload", "agent").to_s : ""
+      end
+
+      def build_prompt(config, messages)
+        base = Coercion.presence(config["prompt"]) || Knowledge::DEFAULT_PROMPT
+        <<~PROMPT
+          #{base.rstrip}
+
+          ## The conversation
+
+          #{render_transcript(messages)}
+        PROMPT
+      end
+
+      def render_transcript(messages)
+        redacted, = Insika::Safety::Detectors.redact(
+          messages.each_with_index.map { |m, i| "[#{i}] #{m['role']}: #{m['content']}" }.join("\n")
+        )
+        redacted
+      end
+
+      def write_concept(profile, session_id, concept, consolidator)
+        outcome = Knowledge.write_concept(store: @knowledge_store, agent_id: profile.id, concept: concept,
+                                          session_id: session_id, consolidator: consolidator)
+        case outcome[:verdict]
+        when :new, :related
+          emit(:knowledge_learned, name: outcome[:name], type: outcome[:type], agent: profile.id)
+        when :contradicting
+          emit(:knowledge_conflict, name: outcome[:name], agent: profile.id)
+        end
+        outcome
+      end
+
+      def utility_model
+        return nil unless @settings_store
+
+        @settings_store.get["utility_model"]
+      end
+
+      def emit(type, **data)
+        @event_stream.emit(Insika::Event.new(type: type, data: data, meta: { at: Time.now.utc.iso8601 }))
+      end
+    end
+  end
+end

data/lib/insika/commands/cancel_followup.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # the operator cancels ONE pending follow-up record (the
+    # Studio's Cancel button dispatches this). Synchronous control command (no
+    # task, like RecordOutcome); idempotent — an already-cancelled record
+    # returns as-is (a repeat of the same call is not an error). Tenant-scoped
+    # (WS1): a tenant principal can only cancel its own tenant's records.
+    class CancelFollowup
+      def initialize(followup_store:, event_stream:)
+        @followup_store = followup_store
+        @event_stream = event_stream
+      end
+
+      # -> Record. Emits :followup_cancelled { id:, cancelled_by: }.
+      def call(command)
+        id = Coercion.presence(command.payload[:followup_id] || command.payload["followup_id"])
+        raise ValidationError, "followup_id is required" if id.nil?
+
+        record = @followup_store.find(id)
+        raise NotFoundError, "follow-up not found: #{id}" if record.nil?
+
+        # WS1: the principal's tenant is the scope — a tenant token cannot
+        # cancel another tenant's record by id.
+        tenant = command.meta[:tenant]
+        unless record.tenant == (tenant.to_s.empty? ? "platform" : tenant.to_s)
+          raise ValidationError, "follow-up #{id} belongs to another tenant"
+        end
+
+        # A non-pending record (the tick fired it between the render and the
+        # click) is a domain error the Studio can flash — never a 500.
+        cancelled = begin
+          @followup_store.cancel(id: id)
+        rescue ArgumentError => e
+          raise ValidationError, e.message
+        end
+        @event_stream.emit(Insika::Event.new(
+                             type: :followup_cancelled,
+                             data: { id: cancelled.id, cancelled_by: "operator" },
+                             meta: { tenant: command.meta[:tenant], at: Time.now.utc.iso8601 }
+                           ))
+        cancelled
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_artifact.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # The Studio's delete on the Artifacts tab — a bus command, like every
+    # Studio mutation (the Studio never writes a store directly). Idempotent:
+    # an unknown id is a no-op, not an error.
+    class DeleteArtifact
+      def initialize(artifact_store:, event_stream:)
+        @artifact_store = artifact_store
+        @event_stream = event_stream
+      end
+
+      # -> { deleted: id } | { deleted: nil } (unknown id).
+      def call(command)
+        id = Coercion.presence(command.payload[:id] || command.payload["id"])
+        raise ValidationError, "id is required" if id.nil?
+
+        deleted = @artifact_store.delete(id.to_s)
+        if deleted
+          @event_stream.emit(Insika::Event.new(
+                               type: :artifact_deleted,
+                               data: { id: id.to_s },
+                               meta: { at: Time.now.utc.iso8601 }
+                             ))
+          { deleted: id.to_s }
+        else
+          { deleted: nil }
+        end
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_concept.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes a learned concept from the KnowledgeStore.
+    # -> { name, agent, tenant, deleted: true }.
+    class DeleteConcept
+      def initialize(knowledge_store:, event_stream:)
+        @knowledge_store = knowledge_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        name = AgentPayload.presence(p[:name])
+        agent = AgentPayload.presence(p[:agent])
+        tenant = AgentPayload.presence(p[:tenant])
+        raise Insika::ValidationError, "name is required" if name.nil?
+        raise Insika::ValidationError, "agent is required" if agent.nil?
+
+        deleted = @knowledge_store.delete(agent, name, tenant: tenant)
+        raise Insika::NotFoundError, "concept '#{name}' not found for agent '#{agent}'" unless deleted
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :knowledge_deleted, data: { name: name, agent: agent },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { name: name, agent: agent, tenant: tenant, deleted: true }
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_mcp.rb

@@ -5,11 +5,14 @@ require "time"
 module Insika
   module Commands
     # Control command: removes an MCP instance from the
-    # McpStore. Idempotent (`existed: false` if there was none). -> { existed: bool }.
+    # McpStore. Idempotent (`existed: false` if there was none). Evicts any
+    # memoized client for this name — a removed instance stops answering
+    # tool calls right away, not after a restart. -> { existed: bool }.
     class DeleteMcp
-      def initialize(mcp_store:, event_stream:)
+      def initialize(mcp_store:, event_stream:, mcp_registry: nil)
         @mcp_store = mcp_store
         @event_stream = event_stream
+        @mcp_registry = mcp_registry
       end
 
       def call(command)
@@ -18,6 +21,7 @@ module Insika
         raise Insika::ValidationError, "name is required" if name.nil?
 
         existed = @mcp_store.delete(name)
+        @mcp_registry&.evict(name)
         @event_stream.emit(Insika::Event.new(
                              type: :mcp_deleted,
                              data: { name: name, existed: existed },