insika 0.3.0 → 0.8.0

data/lib/insika/doctor.rb

@@ -104,7 +104,8 @@ module Insika
                    shadow_pair_store: nil, soak_envelope_path: nil, context_providers: nil,
                    memory_store: nil, agent_ids: nil, funnel_store: nil, outcome_store: nil,
                    followup_store: nil, contact_store: nil, proposal_store: nil,
-                   harvest_store: nil, harvest_criterion: nil)
+                   schedule_store: nil,
+                   harvest_store: nil, harvest_criterion: nil, mcp_store: nil)
       @env = env
       @settings_store = settings_store
       @llm_provider_store = llm_provider_store
@@ -136,10 +137,16 @@ module Insika
       # the distillation check — nil collaborator = the check
       # reports declarations only (counts skipped).
       @proposal_store = proposal_store
+      # the schedules check — nil collaborator = the check
+      # reports declarations only (skip counts skipped).
+      @schedule_store = schedule_store
       # the harvest check — nil collaborators = the check
       # reports declarations only (counts skipped).
       @harvest_store = harvest_store
       @harvest_criterion = harvest_criterion
+      # the mcp check — nil collaborator = the check reports nothing
+      # (env-only callers stay cheap).
+      @mcp_store = mcp_store
     end
 
     # -> Report. Never raises (a broken check degrades to an :error Finding).
@@ -168,11 +175,12 @@ module Insika
     private
 
     def checks = %i[check_env check_settings_schema check_default_model check_db check_llm_provider
-                    check_admin_token check_data_tools check_prompt_files check_relay_channel
-                    check_web_widget check_skill_eager check_skill_drift check_shadow_parity
+                    check_admin_token check_web_concurrency check_data_tools check_mcp check_prompt_files
+                    check_relay_channel check_web_widget check_skill_eager check_skill_drift check_shadow_parity
                     check_soak_envelope check_turn_timing check_grounding check_cache_layers
                     check_memory_scopes check_funnel_declarations check_followup check_distill
-                    check_harvest check_guardrail_corpora]
+                    check_compaction check_harvest check_schedules check_guardrail_corpora
+                    check_tool_allowlist_policy]
 
     def safe(check)
       Array(send(check))
@@ -336,6 +344,54 @@ module Insika
                    message: "ADMIN_TOKEN unset — /studio is fail-closed (login denied) and the gateway has no fallback token", fix: nil)]
     end
 
+    # WEB_CONCURRENCY>1 is a legitimate config (docs/DEPLOY.md "The process
+    # model") — but it silently drops per-worker session guarantees
+    # (FIFO/collect/steer) unless the operator has sticky routing per session in
+    # front, and nothing else in the deployment surfaces that drift. This is
+    # exactly how a staging service ended up at N=4 unnoticed and leaked a reply
+    # across sessions. The engine cannot see whether sticky routing exists off
+    # Railway, so that case only warns — N>1 stays a valid choice for an
+    # operator who put a real sticky proxy in front. On Railway it is not a
+    # valid choice TODAY: Railway's own docs say it "does not support sticky
+    # sessions" and randomly distributes traffic — there is no way to satisfy
+    # the precondition on this platform, so this errors instead of warning.
+    # RAILWAY_ENVIRONMENT_NAME is injected into every Railway deployment
+    # (docs.railway.com/variables/reference), so its presence is a reliable
+    # "are we on Railway" signal.
+    def check_web_concurrency
+      n = @env["WEB_CONCURRENCY"].to_i
+      return [ok("web-concurrency", "WEB_CONCURRENCY=1 (default) — session semantics hold cluster-wide")] if n <= 1
+
+      if router_detected?
+        return [ok("web-concurrency", "WEB_CONCURRENCY=#{n} behind a detected insika-router " \
+                                       "sticky routing satisfies the precondition")]
+      end
+
+      if Insika::Coercion.present?(@env["RAILWAY_ENVIRONMENT_NAME"])
+        return [Finding.new(check: "web-concurrency", severity: :error,
+                             message: "WEB_CONCURRENCY=#{n} on Railway — Railway does not support sticky " \
+                                      "sessions (docs.railway.com/deployments/scaling), so per-session " \
+                                      "FIFO/collect/steer WILL break across workers with no way to fix it " \
+                                      "at the routing layer; set WEB_CONCURRENCY=1, or run insika-router " \
+                                      "in front of N local workers instead", fix: nil)]
+      end
+
+      [Finding.new(check: "web-concurrency", severity: :warn,
+                   message: "WEB_CONCURRENCY=#{n} — per-session FIFO/collect/steer only hold on the worker " \
+                            "that owns the session; make sure sticky routing per session sits in front (e.g. " \
+                            "insika-router, set INSIKA_ROUTER_BACKENDS/_DNS), or accept " \
+                            "per-worker best-effort (docs/DEPLOY.md \"The process model\")", fix: nil)]
+    end
+
+    # A router is "detected", not verified — the doctor cannot see whether a
+    # process at these addresses actually runs `insika-router`, only that the
+    # operator configured one. Same precedent as every other
+    # env-based capability check in this file.
+    def router_detected?
+      Insika::Coercion.present?(@env["INSIKA_ROUTER_BACKENDS"]) ||
+        Insika::Coercion.present?(@env["INSIKA_ROUTER_BACKENDS_DNS"])
+    end
+
     # the soak envelope (a deployment-side file). Absent is :info — not every
     # deployment soaks, and the tooling is optional. Present-and-broken is
     # :error — an envelope that exists but does not parse is a pre-declaration
@@ -667,26 +723,59 @@ module Insika
 # the mangled prompt on every turn, and nothing else would ever say so: the file is
 # present, non-empty, and the agent answers — worse than a crash. Found on the pilot
 # by an `insika refine` report, three weeks after the fact.
+#
+# The same sweep also WARNS (never errors) on a file that outgrew a prompt.
+# Merchant packs are LLM-generated (generate-merchant-pack), and generated prose
+# bloats: the pilot's 28 KB AGENTS.md is the local example, and the ETH Zurich
+# instruction-file study puts the cost of that shape at 20%+ extra tokens per
+# turn for no extra instruction-following. The thresholds are deliberately
+# generous — a hand-written file never meets them; only the generated shape does.
 def check_prompt_files
   return [] unless @agent_file_store
 
   agents = @agent_file_store.agents
-  wrapped = agents.flat_map do |agent|
-    @agent_file_store.list(agent).filter_map do |name|
-      next unless wrapped_content?(@agent_file_store.read(agent, name))
-
-      Finding.new(check: "prompt-files", severity: :error, fix: nil,
-                  message: "agent '#{agent}' file '#{name}' holds a serialized object, not text — " \
-                           "the model receives `{\"content\" => …}` on one line, escapes and all. " \
-                           "Recover the markdown from inside the wrapper and write it back.")
+  wrapped = []
+  oversized = []
+  agents.each do |agent|
+    @agent_file_store.list(agent).each do |name|
+      content = @agent_file_store.read(agent, name)
+      if wrapped_content?(content)
+        wrapped << Finding.new(check: "prompt-files", severity: :error, fix: nil,
+                               message: "agent '#{agent}' file '#{name}' holds a serialized object, not text — " \
+                                        "the model receives `{\"content\" => …}` on one line, escapes and all. " \
+                                        "Recover the markdown from inside the wrapper and write it back.")
+      elsif (finding = oversized_prompt(agent, name, content))
+        oversized << finding
+      end
     end
   end
-  return wrapped if wrapped.any?
+  return wrapped + oversized if wrapped.any? || oversized.any?
 
   total = agents.sum { |a| @agent_file_store.list(a).length }
   [ok("prompt-files", "#{total} prompt file(s) across #{agents.length} agent(s): all text")]
 end
 
+# WARN thresholds for one prompt file. ~6 000 estimated tokens (~24 KB) or 600
+# lines: the pilot's generated 28 KB / 292-line AGENTS.md trips the token bar,
+# every hand-written demo file stays far under both. Estimate = chars/4, the
+# same yardstick as Insika::TokenEstimator — cheap and honest about being ±15%.
+PROMPT_FILE_WARN_TOKENS = 6_000
+PROMPT_FILE_WARN_LINES = 600
+
+def oversized_prompt(agent, name, content)
+  text = content.to_s
+  tokens = Insika::TokenEstimator.estimate(text)
+  lines = text.lines.count
+  return nil if tokens <= PROMPT_FILE_WARN_TOKENS && lines <= PROMPT_FILE_WARN_LINES
+
+  Finding.new(check: "prompt-files", severity: :warn, fix: nil,
+              message: "agent '#{agent}' file '#{name}' is ~#{tokens} tokens over #{lines} line(s) " \
+                       "(threshold: #{PROMPT_FILE_WARN_TOKENS} tokens / #{PROMPT_FILE_WARN_LINES} lines) — " \
+                       "a prompt this large costs 20%+ more tokens on every turn for no better " \
+                       "instruction-following. Trim it, or split the reference material into skills " \
+                       "the agent loads on demand.")
+end
+
 # Cheap and specific: Ruby's inspect of a Hash whose first key is a string. A real
 # prompt does not open with `{"…" =>`.
 def wrapped_content?(content) = /\A\s*\{\s*"[^"]+"\s*=>/.match?(content.to_s)
@@ -694,11 +783,50 @@ def wrapped_content?(content) = /\A\s*\{\s*"[^"]+"\s*=>/.match?(content.to_s)
     def check_data_tools
       return [] unless @tool_store
 
-      broken = @tool_store.all_raw.filter_map { |raw| broken_tool(raw) }
-      total = @tool_store.names.length
-      return [ok("data-tools", "#{total} data tool(s): every definition valid")] if broken.empty?
+      raws = @tool_store.all_raw
+      broken = raws.filter_map { |raw| broken_tool(raw) }
+      legacy = raws.select { |raw| raw["group"].to_s.start_with?("mcp:") }.map { |raw| legacy_mcp_snapshot(raw) }
+      base = broken.empty? ? [ok("data-tools", "#{raws.length} data tool(s): every definition valid")] : broken
+      base + legacy
+    end
+
+    # A data-tool in an `mcp:*` group was ingested by the
+    # RETIRED snapshot path (McpToolIngestor) — the live registry now serves
+    # that same MCP instance's tools directly. Still executes fine (never
+    # removed automatically), just a duplicate worth cleaning up.
+    def legacy_mcp_snapshot(raw)
+      Finding.new(check: "data-tools", severity: :info, fix: nil,
+                  message: "data tool '#{raw["name"]}' (group #{raw["group"]}) is a legacy MCP " \
+                           "snapshot — that instance's tools now run LIVE via the MCP registry; " \
+                           "this frozen copy still works but duplicates it, safe to remove.")
+    end
+
+    # An http/sse instance whose credentials still sit under `env`
+    # (the pre-RFC meaning) is READ as `headers` (McpStore#raw), but the
+    # record on disk is unchanged until the operator re-saves it — flag it so
+    # it doesn't linger silently. A stdio instance that is enabled but
+    # INSIKA_MCP_STDIO is not set will save fine but refuse to start.
+    def check_mcp
+      return [] unless @mcp_store
+
+      raws = @mcp_store.all_raw
+      gated = raws.select do |r|
+        r["transport"].to_s == "stdio" && r["enabled"] &&
+          !Insika::EnvSchema.truthy?(Insika::EnvSchema.read("INSIKA_MCP_STDIO", @env))
+      end
+      findings = @mcp_store.legacy_header_names.map do |name|
+        Finding.new(check: "mcp", severity: :warn, fix: nil,
+                    message: "MCP instance '#{name}' still stores credentials under 'env' — " \
+                             "re-save it so they move to 'headers' (env is now stdio-only).")
+      end
+      findings += gated.map do |r|
+        Finding.new(check: "mcp", severity: :info, fix: nil,
+                    message: "MCP instance '#{r["name"]}' is stdio and enabled, but INSIKA_MCP_STDIO " \
+                             "is not set — it will refuse to start.")
+      end
+      return [ok("mcp", "#{raws.length} MCP instance(s): no legacy env-as-headers records")] if findings.empty?
 
-      broken
+      findings
     end
 
     # the doctor cannot run a turn, so it cannot prove purity — it
@@ -774,6 +902,46 @@ def wrapped_content?(content) = /\A\s*\{\s*"[^"]+"\s*=>/.match?(content.to_s)
     # harmless but useless — every claim passes and the audit reads zero. A
     # warning, never an error: the pack owns matcher quality; the engine refuses
     # only uncompileable data.
+    # A stored agent that declares `tools_allow` / `tools_deny` /
+    # `tools_allow_groups` but does not name the `tool_allowlist` policy. Only
+    # that policy applies the lists, and the Policy::Engine runs ONLY the
+    # policies a profile names — so as written on disk the lists are inert and
+    # the model receives every registered tool (hundreds of schemas, tens of
+    # thousands of tokens, per request).
+    #
+    # AgentProfile.build now adds the policy whenever a list is declared, so a
+    # live turn off this record is already safe. The record itself stays wrong
+    # until something re-saves it, and anything that reads the stored shape
+    # directly — an older engine, a pack export, an operator auditing the
+    # Studio form — still sees an allowlist that does nothing. That is why this
+    # reads the RAW record and not `all`.
+    def check_tool_allowlist_policy
+      return [] unless @profile_source.respond_to?(:all_raw)
+
+      records = @profile_source.all_raw
+      bad = records.select { |r| tool_lists_declared?(r) && !names_tool_allowlist?(r) }
+      return [ok("tool-allowlist", "#{records.length} stored agent(s): every declared tool list names the policy")] if bad.empty?
+
+      bad.map do |r|
+        Finding.new(check: "tool-allowlist", severity: :error, fix: nil,
+                    message: "agent '#{r["id"]}' declares a tool allow/deny list but its policies " \
+                             "(#{Array(r["policies"]).join(", ").then { |p| p.empty? ? "none" : p }}) " \
+                             "do not include tool_allowlist — as stored, the list is never applied and " \
+                             "the model receives every registered tool. The engine repairs this when it " \
+                             "loads the agent; re-save it (Studio, or the pack) so the stored policies " \
+                             "match the intent.")
+      end
+    end
+
+    # Presence, not emptiness, for the two nil-able lists: `tools_allow: []`
+    # means "no tools" and is as much a declaration as a list of names.
+    # `tools_deny` has no nil state, so only a non-empty one counts.
+    def tool_lists_declared?(raw)
+      !raw["tools_allow"].nil? || !raw["tools_allow_groups"].nil? || !Array(raw["tools_deny"]).empty?
+    end
+
+    def names_tool_allowlist?(raw) = Array(raw["policies"]).any? { |p| p.to_s == "tool_allowlist" }
+
     def check_grounding
       return [] unless @profile_source
 
@@ -976,6 +1144,80 @@ def wrapped_content?(content) = /\A\s*\{\s*"[^"]+"\s*=>/.match?(content.to_s)
       e.message
     end
 
+    # the recurring-schedule check — declarations
+    # validated where they are declared (each one through the SAME
+    # Insika::Schedule parser the engine fires on, never a second opinion),
+    # plus the data read that answers "what is being skipped right now".
+    # A bare install (no schedule on any profile) reports NOTHING.
+    def check_schedules
+      return [] unless @profile_source
+
+      declared = @profile_source.all.select do |profile|
+        profile.respond_to?(:schedules) && Array(profile.schedules).any?
+      end
+      return [] if declared.empty?
+
+      declared.flat_map do |profile|
+        Array(profile.schedules).flat_map do |schedule|
+          decl = Insika::Schedule.parse(schedule)
+          if decl.nil?
+            [Finding.new(check: "schedules", severity: :error, fix: nil,
+                         message: "agent '#{profile.id}': malformed schedule — " \
+                                  "#{schedule_defect(schedule)}. The engine will never " \
+                                  "fire it until this is fixed.")]
+          else
+            ok_finding = schedule_ok(profile, decl)
+            [ok_finding] + schedule_data_findings(profile, decl)
+          end
+        end
+      end
+    end
+
+    # The ok finding for one valid declaration — plus the warning that
+    # names the cadence ceiling: the engine claims ONE window per pass, so an
+    # `every` shorter than the claim window cannot fire more often than it.
+    def schedule_ok(profile, decl)
+      trigger = decl.cron ? "cron #{decl.cron} <#{decl.tz}>" : "every #{decl.every}s"
+      floor = Insika::ScheduleEngine::DEFAULT_WINDOW
+      if !decl.cron.nil? || decl.every >= floor
+        ok("schedules",
+           "agent '#{profile.id}': schedule '#{decl.id}' — #{trigger}, " \
+           "#{decl.fixed_session? ? "a fixed standing session" : 'a new session per run'}, " \
+           "#{decl.enabled ? 'enabled' : 'disabled'}")
+      else
+        Finding.new(check: "schedules", severity: :warn, fix: nil,
+                    message: "agent '#{profile.id}': schedule '#{decl.id}' declares " \
+                             "every #{decl.every}s, but the engine fires at most once per " \
+                             "#{floor}s claim window — the effective cadence is one run " \
+                             "per ~#{floor}s, not one per #{decl.every}s.")
+      end
+    end
+
+    # The named defect, for the error message — the engine's parser's words.
+    def schedule_defect(hash)
+      Insika::Schedule.parse!(hash).to_s
+    rescue Insika::ValidationError => e
+      e.message
+    end
+
+    # Data-age findings, gated on the optional collaborator (nil = skip,
+    # env-only callers stay cheap): the row's last skip, when the schedule
+    # was created and has one — visible in the Studio, named here too.
+    def schedule_data_findings(profile, decl)
+      return [] unless @schedule_store
+
+      row = @schedule_store.find(tenant: Insika::ScheduleEngine.tenant_for(profile),
+                                 agent: profile.id.to_s, id: decl.id)
+      return [] unless row&.last_skip
+
+      [Finding.new(check: "schedules", severity: :info, fix: nil,
+                   message: "agent '#{profile.id}' schedule '#{decl.id}': the last run was " \
+                            "SKIPPED at #{row.last_skip['at']} — reason " \
+                            "#{row.last_skip['reason'].inspect} (overlap = the previous " \
+                            "run still live; budget = a hard cap reached; late = the " \
+                            "window was missed by the no-catch-up policy).")]
+    end
+
     # Data-age findings, gated on the optional collaborators (nil = skip,
     # env-only callers stay cheap).
     def followup_data_findings(profile, decl)
@@ -1062,6 +1304,27 @@ def wrapped_content?(content) = /\A\s*\{\s*"[^"]+"\s*=>/.match?(content.to_s)
         stale: @proposal_store.stale(limit: 10_000).size }
     end
 
+    # the in-session compaction check (RFC-0044): platform-gated,
+    # so ONE line — enabled with no resolvable model (no compaction.model, no
+    # platform utility_model) can never run; the warn is the same "declared
+    # but dead" signal as check_distill's (the engine never guesses a model).
+    def check_compaction
+      return [] unless @settings_store
+
+      settings = @settings_store.get
+      config = settings["compaction"] || {}
+      return [ok("compaction", "in-session compaction off")] unless Coercion.truthy?(config["enabled"])
+
+      if Coercion.presence(config["model"]).nil? && Coercion.presence(settings["utility_model"]).nil?
+        [Finding.new(check: "compaction", severity: :warn, fix: nil,
+                     message: "in-session compaction is enabled but has no model slot — it will " \
+                              "never run (set compaction.model or the platform utility_model).")]
+      else
+        [ok("compaction", "in-session compaction on — keep_last #{config['keep_last']}, " \
+                          "compact_after #{config['compact_after']}")]
+      end
+    end
+
     # the harvest check — per profile WITH a harvest hash:
     #   declared-without-model warn (D12), no grounding matcher warn (D3),
     #   malformed negative list error (D4), else ok with the pending counts.

data/lib/insika/dsl/definition.rb

@@ -11,11 +11,12 @@ module Insika
     # exactly like any other pack. That is what makes `#profile` identical to a
     # hand-written equivalent pack (the parity spec) — there is only one path.
     class Definition
-      attr_reader :pack, :runtime_options
+      attr_reader :pack, :runtime_options, :mcp_instances
 
-      def initialize(pack:, runtime: {})
+      def initialize(pack:, runtime: {}, mcp_instances: [])
         @pack = pack
         @runtime_options = runtime
+        @mcp_instances = mcp_instances
       end
 
       def id = pack.config[:id].to_s

data/lib/insika/dsl/runtime.rb

@@ -14,8 +14,6 @@ module Insika
     # Built lazily by Definition#runtime, so `require "insika"` never pays for
     # ruby_llm or the HTTP server.
     class Runtime
-      TERMINAL = %i[task_completed task_failed task_cancelled].freeze
-
       # graph: the assembled Wiring::Graph::Result; pack: the PRIMARY imported
       # Pack; packs: every imported Pack (one per agent — a System has N, a
       # Definition has one). All read by the server boot and the specs.
@@ -40,6 +38,11 @@ module Insika
         # rather than reading a process-wide singleton at call time.
         @llm = build_llm_context
         @graph = build_graph
+        # the dispatch+drain seam `#chat`/`#run_workflow` delegate to —
+        # `Insika::Wiring::GraphChat`, shared with `config/deployment.rb`'s own
+        # registration of `run_persona_eval` (see `register_persona_eval_tool`
+        # below).
+        @chat_runtime = Insika::Wiring::GraphChat.new(graph: @graph)
         seed_default_model
         import_packs
       end
@@ -62,12 +65,8 @@ module Insika
       # one-shot; a value threads multi-turn memory (created on first use).
       # `agent:` targets one agent of a system (default: the primary).
       def chat(message, session_id: nil, timeout: nil, agent: nil)
-        command = Insika::Command.build(
-          :send_message,
-          { agent: (agent || @definition.id).to_s, message: message, session_id: session_id },
-          transport: :cli
-        )
-        run_command(command, session_id: session_id, timeout: timeout)[:text]
+        @chat_runtime.chat(message, agent: (agent || @definition.id).to_s,
+                                    session_id: session_id, timeout: timeout)
       end
 
       # Triggers a declared workflow and returns its OUTPUT (the typed value the
@@ -78,7 +77,7 @@ module Insika
         command = Insika::Command.build(
           :trigger_workflow, { workflow: name, agent: agent, input: input }, transport: :cli
         )
-        outcome = run_command(command, session_id: nil, timeout: timeout)
+        outcome = @chat_runtime.run_command(command, session_id: nil, timeout: timeout)
         outcome.key?(:output) ? outcome[:output] : outcome[:text]
       end
 
@@ -93,70 +92,6 @@ module Insika
 
       private
 
-      # Dispatch + drain, shared by a turn and a workflow run: subscribe BEFORE
-      # dispatching (the fiber may emit eagerly), bind to the task, read to the
-      # terminal event. A synchronous handler error (unknown agent/workflow, bad
-      # input against the schema) propagates from `dispatch` untouched — the
-      # caller sees the real ValidationError/NotFoundError, not a turn failure.
-      def run_command(command, session_id:, timeout:)
-        require "async"
-        outcome = {}
-        rejected = nil
-        Async do |task|
-          serving = !session_id.nil?
-          @graph.executor.supervised = true if serving
-          ensure_session(session_id) if session_id
-          sub = @graph.event_stream.subscribe
-          res = begin
-            @graph.bus.dispatch(command)
-          rescue StandardError => e
-            # CAPTURED, not re-raised inside the reactor: letting it escape the
-            # Async block logs "Task may have ended with unhandled exception" —
-            # alarming noise for a DOCUMENTED rejection (a schema violation, an
-            # unknown agent). Re-raised verbatim below, outside the reactor.
-            sub.close
-            rejected = e
-            next
-          end
-          sub.bind(task_id: res[:task_id])
-          drain(sub, outcome, task, timeout)
-          teardown_serving if serving
-        end.wait
-        raise rejected if rejected
-        raise Insika::Error, "turn #{outcome[:error]}" if outcome[:error]
-
-        outcome
-      end
-
-      # Reads the stream until this turn reaches a terminal event, then stops.
-      # A workflow run also carries its typed OUTPUT, which is not the turn text.
-      def drain(sub, outcome, task, timeout)
-        reader = task.async do
-          sub.each do |ev|
-            case ev.type
-            when :task_completed      then outcome[:text] = ev.data[:content].to_s
-            when :workflow_completed  then outcome[:output] = ev.data[:output]
-            when :task_failed         then outcome[:error] = "failed: #{ev.data[:message] || ev.data[:error]}"
-            when :task_cancelled      then outcome[:error] = "cancelled"
-            end
-            sub.close if TERMINAL.include?(ev.type)
-          end
-        end
-        timeout ? task.with_timeout(timeout) { reader.wait } : reader.wait
-      rescue Async::TimeoutError
-        outcome[:error] = "timed out after #{timeout}s"
-        sub.close
-      end
-
-      def ensure_session(session_id)
-        @graph.session_store.find(session_id) || @graph.session_store.create(id: session_id, vars: {})
-      end
-
-      def teardown_serving
-        @graph.executor.stop_session_actors
-        @graph.executor.instance_variable_get(:@supervisor)&.stop
-      end
-
       # --- graph assembly (mirrors config/deployment.rb, generically) ------
 
       def build_graph
@@ -183,6 +118,20 @@ module Insika
         )
         register_authoring_commands(graph, c)
         register_workflows(graph)
+        import_mcp_declarations(c)
+        # `run_persona_eval` (C3.1): the SAME registration `config/deployment.rb`
+        # does for its own graph — see `Wiring::Graph.register_persona_eval_tool`.
+        # One implementation, both roots; this one just already has its
+        # `golden_store`/`settings_store` at hand from `build_components`.
+        Insika::Wiring::Graph.register_persona_eval_tool(
+          graph, golden_store: Insika::GoldenStore.new(config_store: c[:config_store]),
+          settings_store: c[:settings_store], llm: @llm
+        )
+        # Same boot step the server roots run: an installed `insika-plugin-*`
+        # gem (or INSIKA_PLUGIN_DIR) extends a DSL-run agent too — a plugin
+        # works everywhere or it is not a plugin. No bundled root here: the DSL
+        # runs outside the repo checkout.
+        Insika::Wiring::Graph.load_plugins(graph)
         graph
       end
 
@@ -210,15 +159,42 @@ module Insika
                                               ))
       end
 
+      # Upserts every DSL-declared `mcp` instance into the McpStore at boot.
+      # Code is the TEMPLATE — transport/command/args/url/
+      # description always follow the declaration — but `enabled` and the
+      # credentials (`env`/`headers`) are the operator's once the instance
+      # exists: an already-present record's own values are re-sent verbatim
+      # instead of the DSL's, so a Studio/CLI/API edit made after boot is never
+      # clobbered by the next restart (motor-vs-forja: the store's DATA wins).
+      def import_mcp_declarations(c)
+        declared = Array(@definition.mcp_instances)
+        return if declared.empty?
+
+        mcp_store = c[:mcp_store]
+        declared.each do |decl|
+          attrs = decl.dup
+          existing = mcp_store.get_raw(attrs[:name])
+          if existing
+            attrs[:enabled] = existing["enabled"]
+            attrs[:env] = existing["env"]
+            attrs[:headers] = existing["headers"]
+          end
+          mcp_store.upsert(attrs)
+        end
+      end
+
       def build_components(backend, spine)
         config_store = Insika::ConfigStore.new(store: backend)
         settings_store = Insika::SettingsStore.new(config_store: config_store)
         provider_store = Insika::LLMProviderStore.new(config_store: config_store)
         tool_store = Insika::ToolStore.new(config_store: config_store)
         skill_store = Insika::SkillStore.new(config_store: config_store)
+        mcp_store = Insika::McpStore.new(config_store: config_store)
+        mcp_tool_registry = Insika::McpToolRegistry.new(mcp_store: mcp_store)
         tool_registry = Insika::OverlayToolRegistry.new(
           base: spine.code_tool_registry, tool_store: tool_store,
-          http: Insika::HttpClient.new, event_stream: spine.event_stream
+          http: Insika::HttpClient.new, event_stream: spine.event_stream,
+          mcp_registry: mcp_tool_registry
         )
         {
           backend: backend, config_store: config_store,
@@ -227,7 +203,7 @@ module Insika
           agent_file_store: Insika::AgentFileStore.new(config_store: config_store),
           skill_store: skill_store, tool_store: tool_store,
           system_file_store: Insika::SystemFileStore.new(config_store: config_store),
-          mcp_store: Insika::McpStore.new(config_store: config_store),
+          mcp_store: mcp_store, mcp_tool_registry: mcp_tool_registry,
           tool_trace_store: Insika::ToolTraceStore.new(store: backend),
           context_trace_store: Insika::ContextTraceStore.new(store: backend),
           # the per-AGENT cache-hit series (the Studio agent-detail card).
@@ -252,15 +228,20 @@ module Insika
         [
           Insika::Context::Providers::Request.new,
           Insika::Context::Providers::Prompt.new(
-            base: "", files: [], catalog: c[:prompt_catalog],
+            base: "", catalog: c[:prompt_catalog],
             agent_files: c[:agent_file_store], system_files: c[:system_file_store]
           ),
           Insika::Context::Providers::Skill.new(catalog: c[:skill_catalog]),
           Insika::Context::Providers::SkillTrigger.new(catalog: c[:skill_catalog]),
           Insika::Context::Providers::ToolSearch.new(catalog: c[:tool_catalog]),
           Insika::Context::Providers::Memory.new(store: spine.memory_store),
+          Insika::Context::Providers::Knowledge.new(store: spine.knowledge_store),
+          # Session briefing: read path. Inert for agents without briefing_fields.
+          # Before Session, so the durable head renders above the transcript and
+          # the tail recitation lands after it.
+          Insika::Context::Providers::Briefing.new(session_store: spine.session_store),
           Insika::Context::Providers::Session.new(session_store: spine.session_store)
-        ].freeze
+        ] # NOT frozen: load_plugins appends plugin providers at boot
       end
 
       # The runtime-authoring surface a pack import needs (create_agent +
@@ -288,14 +269,18 @@ module Insika
         bus.register(:update_settings, Insika::Commands::UpdateSettings.new(settings_store: c[:settings_store], event_stream: es))
         bus.register(:upsert_llm_provider, Insika::Commands::UpsertLLMProvider.new(provider_store: c[:provider_store], configurator: c[:configurator], event_stream: es))
         bus.register(:delete_llm_provider, Insika::Commands::DeleteLLMProvider.new(provider_store: c[:provider_store], configurator: c[:configurator], event_stream: es))
-        bus.register(:upsert_mcp, Insika::Commands::UpsertMcp.new(mcp_store: c[:mcp_store], event_stream: es))
-        bus.register(:delete_mcp, Insika::Commands::DeleteMcp.new(mcp_store: c[:mcp_store], event_stream: es))
+        bus.register(:upsert_mcp, Insika::Commands::UpsertMcp.new(mcp_store: c[:mcp_store], mcp_registry: c[:mcp_tool_registry], event_stream: es))
+        bus.register(:delete_mcp, Insika::Commands::DeleteMcp.new(mcp_store: c[:mcp_store], mcp_registry: c[:mcp_tool_registry], event_stream: es))
+        bus.register(:refresh_mcp_tools, Insika::Commands::RefreshMcpTools.new(mcp_registry: c[:mcp_tool_registry], event_stream: es))
         bus.register(:write_system_file, Insika::Commands::WriteSystemFile.new(system_file_store: c[:system_file_store], event_stream: es))
         bus.register(:delete_system_file, Insika::Commands::DeleteSystemFile.new(system_file_store: c[:system_file_store], event_stream: es))
         bus.register(:restore_system_file, Insika::Commands::RestoreSystemFile.new(system_file_store: c[:system_file_store], event_stream: es))
         bus.register(:write_data_tool, Insika::Commands::WriteDataTool.new(tool_store: c[:tool_store], registry: c[:tool_registry], tool_catalog: c[:tool_catalog], event_stream: es))
         bus.register(:delete_data_tool, Insika::Commands::DeleteDataTool.new(tool_store: c[:tool_store], registry: c[:tool_registry], tool_catalog: c[:tool_catalog], event_stream: es))
         bus.register(:restore_data_tool, Insika::Commands::RestoreDataTool.new(tool_store: c[:tool_store], registry: c[:tool_registry], tool_catalog: c[:tool_catalog], event_stream: es))
+        bus.register(:write_concept, Insika::Commands::WriteConcept.new(knowledge_store: graph.knowledge_store, event_stream: es))
+        bus.register(:delete_concept, Insika::Commands::DeleteConcept.new(knowledge_store: graph.knowledge_store, event_stream: es))
+        bus.register(:restore_concept, Insika::Commands::RestoreConcept.new(knowledge_store: graph.knowledge_store, event_stream: es))
       end
 
       # --- RubyLLM configuration ------------------------------------------

data/lib/insika/dsl/server_boot.rb

@@ -51,6 +51,10 @@ module Insika
         Insika::Shutdown.install(executor: @graph.executor)
         Async do
           @graph.executor.supervised = true # serving mode: turns survive disconnects
+          # forces the tick/alert/distill/harvest supervisor up now — otherwise a
+          # deployment with only scheduled agents (no live chat) never ticks until
+          # unrelated traffic happens to hit turn_parent first.
+          @graph.executor.start_supervisor!
           Insika::Telemetry.attach(event_stream: @graph.event_stream, recorder: telemetry)
           Async::HTTP::Server.new(middleware, endpoint).run
         end
@@ -122,10 +126,28 @@ module Insika
           # (nil = the page renders the refusal/empty states).
           harvest_store: @graph.harvest_store,
           harvest_criterion: harvest_criterion,
-          negative_list: harvest_negative_list
+          negative_list: harvest_negative_list,
+          # the Knowledge page reads the store directly; its
+          # mutations (write/delete/restore) dispatch bus commands.
+          knowledge_store: @graph.knowledge_store,
+          # the Artifacts tab reads the report store; the signing
+          # config (nil without INSIKA_ARTIFACT_SIGNING_KEY) decides whether a
+          # signed sharing link exists at all.
+          artifact_store: @graph.artifact_store,
+          artifact_signing: artifact_signing
         )
       end
 
+      # -> { key:, ttl:, base_url: } | nil (no signing key -> no signed surface).
+      def artifact_signing
+        key = Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_KEY")
+        return nil if key.to_s.empty?
+
+        { key: key,
+          ttl: (Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_TTL") || 604_800).to_i,
+          base_url: Insika::Coercion.presence(Insika::EnvSchema.read("INSIKA_PUBLIC_URL")).to_s }
+      end
+
       # The frozen criterion — best-effort at boot: a bare install
       # without the env var renders the ruler's hole instead of
       # crashing the Studio.