insika 0.3.0 → 0.8.0

data/lib/insika/wiring/graph.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "graph_chat"
+
 module Insika
   module Wiring
     # SHARED composition core for both roots: the minimal wiring
@@ -78,11 +80,21 @@ module Insika
         # followup) so the engine, the tools and the Studio always have stores.
         contact_store       = Insika::ContactStore.new(store: backend)
         followup_store      = Insika::FollowupStore.new(store: backend)
+        # the recurring-schedule rows: one row per
+        # declared schedule, declaration + runtime state. Built unconditionally
+        # (empty and free when no pack declares schedules) so the engine, the
+        # doctor and the Studio always have a store.
+        schedule_store      = Insika::ScheduleStore.new(store: backend)
         # the distilled proposals + the latched dedup ledger +
         # the per-session markers. Built unconditionally (empty and free when
         # no pack declares distill) so the wiki, the engine and the LGPD
         # purges always have a store.
         proposal_store      = Insika::ProposalStore.new(store: backend)
+        # concepts extracted from finished turns. Built
+        # unconditionally (empty and free when no pack declares knowledge)
+        # so the extractor, the Studio and the LGPD purges always have a
+        # store.
+        knowledge_store      = Insika::KnowledgeStore.new(store: backend)
         # refinement RUNS (reports over real traffic). Runtime data,
         # same backend as sessions/tasks — the collector and the command that write it
         # are the root's business (deployment-only, like the memory commands).
@@ -93,6 +105,11 @@ module Insika
         # when no pack declares harvest) so the engine, the Studio and the
         # LGPD purges always have a store.
         harvest_store        = Insika::HarvestStore.new(store: backend)
+        # the report destination — one record per run, no
+        # versioning. Built unconditionally (empty and free when nothing saves)
+        # so the tool, the routes, the retention sweep and the tenant purge
+        # always have a store.
+        artifact_store       = Insika::ArtifactStore.new(store: backend)
 
         code_tool_registry = Insika::ToolRegistry.new
         workflow_registry  = Insika::WorkflowRegistry.new
@@ -118,7 +135,10 @@ module Insika
           funnel_store: funnel_store,
           contact_store: contact_store,
           followup_store: followup_store,
+          schedule_store: schedule_store,
           proposal_store: proposal_store,
+          knowledge_store: knowledge_store,
+          artifact_store: artifact_store,
           code_tool_registry: code_tool_registry,
           workflow_registry: workflow_registry, policy_registry: policy_registry,
           capability_registry: Insika::CapabilityRegistry.new, hooks: Insika::Hooks.new,
@@ -141,6 +161,13 @@ module Insika
       def build(spine:, profiles:, tool_registry:, tool_catalog:, skill_catalog:,
                 prompt_catalog:, guardrails:, context_providers:, edge_limiter: nil,
                 executor_extra: {})
+        # the save_artifact tool: a REGISTRY tool registered OPTIONAL (the
+        # per-agent allowlist is the switch — an agent that did not name it
+        # cannot call it). Registered in the shared code registry, so both
+        # roots (base registry + the deployment's overlay, which composes it)
+        # expose it. The gem's require lives IN the factory block (loaded on
+        # the 1st instance, turn time -> wiring-load stays gem-free).
+        register_artifact_tool(spine)
         spine.hooks.register(:task, after: guardrails.output_validator)
         middleware = Insika::MiddlewareStack.new([edge_limiter, guardrails.input_guardrail].compact)
 
@@ -188,6 +215,9 @@ module Insika
         # parity). The base graph wires it over the same backend the context
         # trace uses.
         model_visible_trace_store: Insika::ModelVisibleTraceStore.new(store: spine.backend),
+        # the per-turn extraction hook (nil = the loop is off,
+        # parity). Gated per-agent by `profile.knowledge`.
+        knowledge_store: spine.knowledge_store,
         **executor_extra
       )
 
@@ -233,7 +263,8 @@ module Insika
             followup_store: spine.followup_store, # records age out too
             contact_store: spine.contact_store, # cells age out too
             proposal_store: spine.proposal_store, # proposals age out too
-            harvest_store: spine.harvest_store # candidates/log/snapshots too
+            harvest_store: spine.harvest_store, # candidates/log/snapshots too
+            artifact_store: spine.artifact_store # reports expire on their own TTL
           ),
           interval: tick_env("INSIKA_TICK_INTERVAL") || Insika::Tick::DEFAULT_INTERVAL,
           stale_after: tick_env("INSIKA_TICK_STALE_AFTER") || Insika::Tick::DEFAULT_STALE_AFTER
@@ -256,6 +287,16 @@ module Insika
           contact_store: spine.contact_store, task_store: spine.task_store,
           profiles: profiles, executor: executor, event_stream: spine.event_stream
         )
+        # the recurring-schedule firer — the tick's
+        # fourth duty, wired here after the Tick, gated by its own claim
+        # window. Always built: a pack that declares `schedules` later finds
+        # its firer already on the tick (inert when no profile declares one).
+        executor.tick.schedule = Insika::ScheduleEngine.new(
+          store: spine.backend, schedule_store: spine.schedule_store,
+          task_store: spine.task_store, session_store: spine.session_store,
+          profiles: profiles, executor: executor, budget_ledger: spine.budget_ledger,
+          event_stream: spine.event_stream
+        )
         # the distillation engine — the tick-duty that finds idle
         # customer sessions and distills them on its own worker fiber (a
         # supervisor child, started in serving mode next to the tick).
@@ -307,13 +348,16 @@ module Insika
           memory_store: spine.memory_store, memory_audit_store: spine.memory_audit_store,
           refinement_store: spine.refinement_store,
           harvest_store: spine.harvest_store,
+          artifact_store: spine.artifact_store,
           outbox_store: spine.outbox_store, shadow_pair_store: spine.shadow_pair_store,
           inbound_log: spine.inbound_log,
           outcome_store: spine.outcome_store,
           funnel_store: spine.funnel_store,
           contact_store: spine.contact_store,
           followup_store: spine.followup_store,
+          schedule_store: spine.schedule_store,
           proposal_store: spine.proposal_store,
+          knowledge_store: spine.knowledge_store,
           token_store: spine.token_store, budget_ledger: spine.budget_ledger,
           circuit_state: spine.circuit_state,
           channel_registry: spine.channel_registry, channel_delivery: channel_delivery,
@@ -327,6 +371,49 @@ module Insika
         )
       end
 
+      # The boot step behind every root's `load_plugins` (Server::Boot's first
+      # named step). Discovers plugin manifests, validates them, requires the
+      # entries and registers their contributions into the ALREADY-BUILT graph —
+      # which is safe by construction: every seam the Loader touches resolves at
+      # turn time (registries and hooks by name, the middleware stack and the
+      # provider list per call, the catalogs on reload), and the step runs
+      # single-fiber before the server accepts connections.
+      #
+      # Roots, highest precedence first (duplicate id -> first root wins):
+      #   1. workspace  — INSIKA_PLUGIN_DIR (the operator's override spot);
+      #   2. gems       — whatever called Insika::Plugin.announce (default-enabled);
+      #   3. bundled    — `bundled_root` (the repo's plugins/; requires enabling).
+      # INSIKA_PLUGINS enables workspace/bundled ids; INSIKA_PLUGINS_DISABLED is
+      # the absolute veto (deny wins, like every allowlist in the engine).
+      def load_plugins(graph, env: ENV, bundled_root: nil)
+        announced = Insika::Plugin.announced_roots
+        workspace = Insika::EnvSchema.read("INSIKA_PLUGIN_DIR", env)
+        roots = ([workspace] + announced + [bundled_root]).compact.map { |d| File.expand_path(d.to_s) }
+
+        result = Insika::Plugin::Loader.new(
+          roots: roots,
+          registries: {
+            tools: graph.code_tool_registry, workflows: graph.workflow_registry,
+            policies: graph.policy_registry, capabilities: graph.capability_registry,
+            channels: graph.channel_registry, hooks: graph.hooks,
+            middleware: graph.middleware, context_providers: graph.context_providers
+          },
+          enabled: plugin_csv(Insika::EnvSchema.read("INSIKA_PLUGINS", env)),
+          disabled: plugin_csv(Insika::EnvSchema.read("INSIKA_PLUGINS_DISABLED", env)),
+          announced_roots: announced, event_stream: graph.event_stream
+        ).load_all
+
+        # Plugin knowledge joins at the LOWEST precedence: an operator's
+        # workspace/authored skill always beats a same-named plugin one.
+        graph.skill_catalog.add_roots(result[:skill_dirs])
+        graph.prompt_catalog.add_roots(result[:prompt_dirs])
+        result
+      end
+
+      def plugin_csv(value)
+        value.to_s.split(",").map(&:strip).reject(&:empty?)
+      end
+
       # The CORE command surface every root needs — turn essentials + the operator
       # controls (pause/approve) the Studio dispatches. Registering pause_task/
       # approve_action HERE is the crux of: it retires the config.ru:28-34 patch.
@@ -411,16 +498,18 @@ module Insika
                        model_visible_trace_store: Insika::ModelVisibleTraceStore.new(store: spine.backend),
                        outcome_store: spine.outcome_store,
                        funnel_store: spine.funnel_store, # the fold dies with the tenant
-                       followup_store: spine.followup_store,
-                       contact_store: spine.contact_store,
-                       proposal_store: spine.proposal_store,
-                       harvest_store: spine.harvest_store,
-                       task_store: spine.task_store, checkpoint_store: spine.checkpoint_store,
-                       outbox_store: spine.outbox_store,
-                       shadow_pairs: spine.shadow_pair_store,
-                       token_store: spine.token_store, # revoked BEFORE the sweep
-                       event_stream: spine.event_stream
-                     ))
+                        followup_store: spine.followup_store,
+                        contact_store: spine.contact_store,
+                        proposal_store: spine.proposal_store,
+                        harvest_store: spine.harvest_store,
+                        schedule_store: spine.schedule_store,
+                        artifact_store: spine.artifact_store,
+                        task_store: spine.task_store, checkpoint_store: spine.checkpoint_store,
+                          outbox_store: spine.outbox_store,
+                          shadow_pairs: spine.shadow_pair_store,
+                          token_store: spine.token_store, # revoked BEFORE the sweep
+                          event_stream: spine.event_stream
+                        ))
         # the operator's baseline freeze — the number
         # read. Synchronous control command, dispatched from the Studio.
         bus.register(:freeze_funnel_baseline,
@@ -434,6 +523,12 @@ module Insika
         bus.register(:cancel_followup,
                      Insika::Commands::CancelFollowup.new(followup_store: spine.followup_store,
                                                           event_stream: spine.event_stream))
+        # the report destination's Studio mutation — delete one
+        # artifact (the only write on the Artifacts tab; a bus command, like
+        # every Studio mutation).
+        bus.register(:delete_artifact,
+                     Insika::Commands::DeleteArtifact.new(artifact_store: spine.artifact_store,
+                                                          event_stream: spine.event_stream))
         bus.register(:revoke_contact,
                      Insika::Commands::RevokeContact.new(contact_store: spine.contact_store,
                                                          followup_store: spine.followup_store,
@@ -493,6 +588,23 @@ module Insika
         # code path; the engine keeps the automatic pass when the root does
         # not pass a runner here (nil = the command is not on the bus).
         bus.register(:run_distillation, run_distillation) if run_distillation
+        # the demo seed's ONE path — the CLI's `insika demo:seed` builds
+        # the same Insika::Demo::Seeder itself (no executor, no bus, from
+        # Graph.spine alone), and the Studio's "Seed demo data" button
+        # dispatches this bus command; nothing else writes the demo agent.
+        config_store = Insika::ConfigStore.new(store: spine.backend)
+        demo_seeder = Insika::Demo::Seeder.new(
+          profiles: profiles, store: spine.backend, session_store: spine.session_store,
+          task_store: spine.task_store, outcome_store: spine.outcome_store,
+          funnel_store: spine.funnel_store, followup_store: spine.followup_store,
+          refinement_store: spine.refinement_store, pending_action_store: spine.pending_action_store,
+          proposal_store: spine.proposal_store, memory_store: spine.memory_store,
+          golden_store: Insika::GoldenStore.new(config_store: config_store),
+          baseline_store: Insika::BaselineStore.new(config_store: config_store),
+          event_stream: spine.event_stream
+        )
+        bus.register(:seed_demo_data,
+                     Insika::Commands::SeedDemoData.new(seeder: demo_seeder, event_stream: spine.event_stream))
         bus
       end
 
@@ -505,7 +617,9 @@ module Insika
         :harvest_store,
         :token_store, :budget_ledger, :circuit_state, :outbox_store, :shadow_pair_store,
         :inbound_log, :outcome_store, :funnel_store,
-        :contact_store, :followup_store, :proposal_store,
+        :contact_store, :followup_store, :schedule_store, :proposal_store,
+        :knowledge_store,
+        :artifact_store,
         :code_tool_registry, :workflow_registry, :policy_registry, :capability_registry, :hooks,
         :channel_registry, keyword_init: true
       )
@@ -520,7 +634,10 @@ module Insika
         :inbound_log, :token_store,
         :budget_ledger, :circuit_state, :outcome_store, :funnel_store,
         :contact_store, :followup_store, :proposal_store,
+        :schedule_store,
         :harvest_store,
+        :knowledge_store,
+        :artifact_store,
         :channel_registry, :channel_delivery,
         :code_tool_registry, :tool_registry, :workflow_registry, :policy_registry, :capability_registry,
         :tool_catalog, :skill_catalog, :prompt_catalog,
@@ -531,6 +648,61 @@ module Insika
       ) do
         def durable? = backend.is_a?(Insika::Stores::SQLite)
       end
+
+      # The save_artifact tool, registered OPTIONAL on the shared code registry
+      # (the per-agent allowlist is the switch). The signing/base config is
+      # bound at registration time from the environment — the tool instance is
+      # per-deployment, and the tenant/agent/task bindings arrive per-turn via
+      # the deposited turn context.
+      # `run_persona_eval` (C3.1): a QA agent's own probe against a SIBLING
+      # agent of THIS SAME graph. Registered OPTIONAL on the shared code
+      # registry, same switch as `save_artifact` — but unlike that one, this
+      # is NOT called unconditionally from `build`: it needs a `golden_store`
+      # and a `settings_store` (the persona model + judge panel), and neither
+      # lives on the spine (the base/minimal wiring builds without either, the
+      # same way it builds without a Studio) — so each root calls this itself,
+      # once it has both. `config/deployment.rb` (round1, and the actual
+      # production `config.ru` root) and `DSL::Runtime` both do.
+      #
+      # `graph` is the ALREADY-RETURNED `Graph::Result` — bus/executor fully
+      # assembled by the time a caller has it to pass here, so `GraphChat.new`
+      # needs no laziness of its own (the tool's own factory block is what is
+      # lazy — this method just registers it).
+      # `llm:` — the caller's own RubyLLM::Context, when it has one
+      # (DSL::Runtime does; config/deployment.rb does not, and reads the
+      # process-wide RubyLLM constant like the rest of that root already
+      # does). Forwarded as-is so the tool's OWN persona/judge calls spend
+      # the right credentials instead of silently defaulting to nil.
+      def register_persona_eval_tool(graph, golden_store:, settings_store:, llm: nil)
+        graph.code_tool_registry.register("run_persona_eval", optional: true) do
+          require "ruby_llm"
+          require_relative "../tools/run_persona_eval"
+          Insika::Tools::RunPersonaEval.new(
+            golden_store: golden_store, profiles: graph.profiles, tool_registry: graph.tool_registry,
+            runtime: GraphChat.new(graph: graph), graph: graph, settings_store: settings_store,
+            budget_ledger: graph.budget_ledger, event_stream: graph.event_stream, llm: llm
+          )
+        end
+      end
+
+      def register_artifact_tool(spine)
+        signing_key = Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_KEY")
+        signing_ttl = Insika::EnvSchema.read("INSIKA_ARTIFACT_SIGNING_TTL")
+        max_bytes = Insika::EnvSchema.read("INSIKA_ARTIFACT_MAX_BYTES")
+        base_url = Insika::Coercion.presence(Insika::EnvSchema.read("INSIKA_PUBLIC_URL"))
+        spine.code_tool_registry.register("save_artifact", optional: true) do
+          require "ruby_llm"
+          require_relative "../tools/save_artifact"
+          Insika::Tools::SaveArtifact.new(
+            artifact_store: spine.artifact_store,
+            base_url: base_url,
+            signing_key: signing_key,
+            signing_ttl: signing_ttl&.to_i,
+            max_bytes: max_bytes&.to_i,
+            event_stream: spine.event_stream
+          )
+        end
+      end
     end
   end
 end

data/lib/insika/wiring/graph_chat.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Insika
+  module Wiring
+    # A synchronous, in-process "chat" seam over an assembled `Graph::Result`:
+    # dispatch a Command, drain the event stream to its terminal event, hand
+    # back the outcome. Extracted from `DSL::Runtime#chat`/`#run_workflow`
+    # (C3.1) so a graph built OUTSIDE the DSL — `config/deployment.rb`, the
+    # actual production/round1 composition root `config.ru` boots — can hand a
+    # `#chat`-capable object to anything that needs one (today:
+    # `run_persona_eval`'s `Evals::GraphTransport` seam), without a second copy
+    # of this dispatch+drain plumbing. `DSL::Runtime` now delegates here too —
+    # one implementation, exercised by both roots.
+    class GraphChat
+      TERMINAL = %i[task_completed task_failed task_cancelled].freeze
+
+      def initialize(graph:)
+        @graph = graph
+      end
+
+      # One turn, in-process -> the assistant's text. `agent:` is REQUIRED —
+      # this seam has no notion of "the default agent" (that is a DSL::Runtime
+      # concept, filled in by its own caller before delegating here). Raises
+      # Insika::Error on a failed/cancelled turn, or the command's own
+      # rejection (unknown agent, bad schema) verbatim.
+      def chat(message, agent:, session_id: nil, timeout: nil)
+        command = Insika::Command.build(
+          :send_message, { agent: agent.to_s, message: message, session_id: session_id },
+          transport: :cli
+        )
+        run_command(command, session_id: session_id, timeout: timeout)[:text]
+      end
+
+      # Dispatch + drain, generic over any Command — the seam a workflow run
+      # also needs (a :trigger_workflow Command carries :output, not :text).
+      # Subscribes BEFORE dispatching (the fiber may emit eagerly) and binds to
+      # the dispatched task. A synchronous handler error (unknown agent/
+      # workflow, bad input against the schema) propagates 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
+
+      private
+
+      # 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
+    end
+  end
+end

data/lib/insika.rb

@@ -1,5 +1,13 @@
 # frozen_string_literal: true
 
+# Templates under lib/insika/templates/*/agent.rb open with a bare
+# `require "insika"` (the line a standalone `ruby agent.rb` run needs) and
+# Templates.evaluate instance_evals that same source in-process — so this
+# file's own directory must be on $LOAD_PATH, or that require raises
+# LoadError whenever nothing else already activated the "insika" gem
+# (no Bundler.setup, no globally installed gem).
+$LOAD_PATH.unshift(__dir__) unless $LOAD_PATH.include?(__dir__)
+
 require_relative "insika/version"
 require_relative "insika/errors"
 # the payload selection + the domain-boundary audit yardstick.
@@ -27,6 +35,20 @@ require_relative "insika/contact_store"
 require_relative "insika/followup_store"
 # the tick-driven firer — rides the same tick as retention/funnel.
 require_relative "insika/followup_engine"
+# IANA zone resolution through the OS tz database — the stdlib-only route
+# to a zone NAME (Follow-up quiet hours, the cron scheduler, the doctor).
+require_relative "insika/timezone"
+# the recurring schedule: the five-field cron subset + next-fire
+# materialization, the declaration parse, the per-agent rows, and the
+# tick-driven firer (the recurring half of the tick).
+require_relative "insika/cron"
+require_relative "insika/schedule"
+require_relative "insika/schedule_store"
+require_relative "insika/schedule_engine"
+# the report destination — one record per run, no
+# versioning; the signing half of the sharing link (HMAC, no secret stored).
+require_relative "insika/artifact_store"
+require_relative "insika/artifact_signing"
 require_relative "insika/commands/freeze_funnel_baseline"
 require_relative "insika/channels/webhook"
 require_relative "insika/coercion"
@@ -81,6 +103,7 @@ require_relative "insika/context/providers/skill"
 require_relative "insika/context/providers/skill_trigger"
 require_relative "insika/context/providers/tool_search"
 require_relative "insika/context/providers/memory"
+require_relative "insika/context/providers/knowledge"
 require_relative "insika/context/providers/session"
 require_relative "insika/context/providers/briefing"
 # the cache-prefix hash chain + the per-agent cache-hit series.
@@ -112,6 +135,7 @@ require_relative "insika/outbox_store"
 require_relative "insika/shadow_pair_store"
 require_relative "insika/inbound_log"
 require_relative "insika/memory_store"
+require_relative "insika/knowledge_store"
 # the operator-mutation audit trail. After memory_store (no
 # mutual deps). Pure stdlib — `load_guard_spec` stays green.
 require_relative "insika/memory_audit_store"
@@ -122,6 +146,7 @@ require_relative "insika/skill_store"
 require_relative "insika/secret_masking"
 require_relative "insika/tool_store"
 require_relative "insika/tool_trace_store"
+require_relative "insika/tool_usage_report"
 require_relative "insika/context_trace_store"
 # the model-visible payload of one ask + its durable trace —
 # "model-visible means logged" (the conformance suite's reconstruction half).
@@ -172,6 +197,10 @@ require_relative "insika/evals/runner"
 require_relative "insika/evals/report"
 require_relative "insika/evals/baseline"
 require_relative "insika/evals/transport"
+# simulated users: the persona data + the conversation driver.
+# Pure — the persona model is an injected ask, the target rides the Transport.
+require_relative "insika/evals/persona"
+require_relative "insika/evals/simulator"
 # shadow parity: the frozen criterion and the mechanical
 # fold over the pair store (C6). Pure — no store, no provider gem.
 require_relative "insika/parity/criterion"
@@ -189,6 +218,14 @@ require_relative "insika/refinement/panel"
 require_relative "insika/mcp_store"
 require_relative "insika/mcp_http_client"
 require_relative "insika/mcp_tool_ingestor"
+# require "ruby_llm/mcp" itself is LAZY, inside .for — this require_relative only
+# loads the thin factory (see spec/insika/load_guard_spec.rb).
+require_relative "insika/mcp_client"
+# insika/mcp_live_tool (< RubyLLM::Tool) is NOT required here — McpToolRegistry
+# require_relative's it lazily on the 1st instance (turn time), same as
+# OverlayToolRegistry does for tools/data_defined_tool.
+require_relative "insika/mcp_tool_registry"
+require_relative "insika/mcp_json"
 require_relative "insika/system_file_store"
 require_relative "insika/recovery"
 require_relative "insika/command_bus"
@@ -236,6 +273,13 @@ require_relative "insika/commands/export_customer_memory"
 # record; revoke a contact + fall its pending records atomically).
 require_relative "insika/commands/cancel_followup"
 require_relative "insika/commands/revoke_contact"
+# the report destination's Studio mutation — delete one artifact
+# (a bus command, like every Studio mutation).
+require_relative "insika/commands/delete_artifact"
+# in-session compaction (RFC-0044) — the summarizer (pure, injected
+# ask) and the boundary math; the trigger lives in the Executor, the
+# persistence in SessionStore, the read path in the Session provider.
+require_relative "insika/compaction"
 # session distillation — the distiller (pure, injected ask)
 # and the proposal store (proposals + the latched dedup ledger + the
 # per-session distilled marker).
@@ -259,6 +303,15 @@ require_relative "insika/commands/promote_harvest"
 require_relative "insika/commands/rollback_harvest"
 require_relative "insika/commands/reject_harvest"
 require_relative "insika/harvest_engine"
+# post-turn learning — the extractor (pure, injected ask) and the
+# concept format itself (markdown + YAML frontmatter, the SkillCatalog
+# split). The provider touch stays inside ExtractorFactory's lazy ask
+# (load_guard stays green).
+require_relative "insika/knowledge"
+require_relative "insika/commands/backfill_knowledge"
+require_relative "insika/commands/write_concept"
+require_relative "insika/commands/delete_concept"
+require_relative "insika/commands/restore_concept"
 require_relative "insika/commands/upsert_mcp"
 require_relative "insika/commands/delete_mcp"
 require_relative "insika/commands/write_system_file"
@@ -269,6 +322,14 @@ require_relative "insika/commands/delete_data_tool"
 require_relative "insika/commands/restore_data_tool"
 require_relative "insika/commands/import_tools"
 require_relative "insika/commands/import_mcp_tools"
+require_relative "insika/commands/refresh_mcp_tools"
+# the demo seed (OSS onboarding): one bundled agent + golden
+# set + the Seeder that populates every loop's stores at once, and its bus
+# adapter for `insika demo:seed` and the Studio's "Seed demo data" button.
+require_relative "insika/demo/agent_attrs"
+require_relative "insika/demo/golden_cases"
+require_relative "insika/demo/seeder"
+require_relative "insika/commands/seed_demo_data"
 require_relative "insika/event_stream"
 require_relative "insika/task_actor"
 require_relative "insika/queue_policy"
@@ -276,7 +337,9 @@ require_relative "insika/session_actor"
 require_relative "insika/skill_catalog"
 require_relative "insika/tool_catalog"
 require_relative "insika/steer_injector"
+require_relative "insika/tool_batch"
 require_relative "insika/loop_detector"
+require_relative "insika/turn_budget"
 require_relative "insika/balloon_splitter"
 require_relative "insika/turn_output"
 require_relative "insika/turn_state"
@@ -290,6 +353,7 @@ require_relative "insika/shutdown"
 require_relative "insika/tick"
 require_relative "insika/pack"
 require_relative "insika/pack_importer"
+require_relative "insika/templates"
 require_relative "insika/telemetry"
 # Strict config + diagnosis. Doctor reads the config stores above;
 # EnvSchema (required at the top) is its env layer.