insika 0.2.0 → 0.7.0

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
@@ -178,10 +113,25 @@ module Insika
           guardrails: c[:guardrails], context_providers: context_providers(spine, c),
           edge_limiter: c[:edge_limiter],
           executor_extra: { settings_store: c[:settings_store], tool_trace_store: c[:tool_trace_store],
-                            context_trace_store: c[:context_trace_store], llm: @llm }
+                            context_trace_store: c[:context_trace_store],
+                            cache_series_store: c[:cache_series_store], llm: @llm }
         )
         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
 
@@ -209,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,
@@ -226,9 +203,11 @@ 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).
+          cache_series_store: Insika::CacheSeriesStore.new(store: backend),
           tool_registry: tool_registry,
           tool_catalog: Insika::ToolCatalog.new(tool_registry: tool_registry),
           skill_catalog: Insika::SkillCatalog.new([], store: skill_store),
@@ -249,15 +228,16 @@ 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),
           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 +
@@ -267,6 +247,7 @@ module Insika
         bus = graph.bus
         es = graph.event_stream
         mem = graph.memory_store
+        audit = graph.memory_audit_store
         bus.register(:create_agent, Insika::Commands::CreateAgent.new(profile_source: c[:profile_source], event_stream: es))
         bus.register(:update_agent, Insika::Commands::UpdateAgent.new(profile_source: c[:profile_source], event_stream: es))
         bus.register(:delete_agent, Insika::Commands::DeleteAgent.new(profile_source: c[:profile_source], event_stream: es))
@@ -276,20 +257,26 @@ module Insika
         bus.register(:restore_agent_file, Insika::Commands::RestoreAgentFile.new(profile_source: c[:profile_source], agent_file_store: c[:agent_file_store], event_stream: es))
         bus.register(:write_skill, Insika::Commands::WriteSkill.new(skill_store: c[:skill_store], skill_catalog: c[:skill_catalog], event_stream: es))
         bus.register(:set_skill_agents, Insika::Commands::SetSkillAgents.new(profile_source: c[:profile_source], event_stream: es))
-        bus.register(:memory_put_fact, Insika::Commands::MemoryPutFact.new(memory_store: mem, event_stream: es))
-        bus.register(:memory_forget_fact, Insika::Commands::MemoryForgetFact.new(memory_store: mem, event_stream: es))
+        bus.register(:memory_put_fact, Insika::Commands::MemoryPutFact.new(memory_store: mem, event_stream: es, audit_store: audit))
+        bus.register(:memory_forget_fact, Insika::Commands::MemoryForgetFact.new(memory_store: mem, event_stream: es, audit_store: audit))
         bus.register(:memory_add_note, Insika::Commands::MemoryAddNote.new(memory_store: mem, event_stream: es))
+        # the LGPD access right — the Studio Customers drill exports.
+        bus.register(:export_customer_memory, Insika::Commands::ExportCustomerMemory.new(memory_store: mem, event_stream: es))
         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

@@ -31,6 +31,11 @@ module Insika
       end
 
       def run
+        # The boot refusal (shadow + no criterion) lives in the AppBuilder; run it
+        # BEFORE the Studio is configured so the criterion the Studio folds is the
+        # same object the delivery path stamps pairs with.
+        @builder.channels?
+        register_parity_commands
         configure_studio
         dispatch = Rack::URLMap.new("/studio" => Studio::App, "/" => @builder.app)
         endpoint = Async::HTTP::Endpoint.parse("http://#{@host}:#{@port}")
@@ -46,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
@@ -56,6 +65,23 @@ module Insika
       def workflows? = @builder.workflows?
       def channels? = @builder.channels?
 
+      # The parity page renders whenever a shadow channel exists, so the judge
+      # button must reach a registered command — the deployment bus registers the
+      # same one (config/deployment.rb); a page that answers "unknown command"
+      # would make this root a second-class citizen. Registered only when the
+      # criterion loaded (a command without one would be a fake judge).
+      def register_parity_commands
+        criterion = @builder.criterion
+        return unless criterion
+
+        @graph.bus.register(:judge_shadow_pairs,
+                            Insika::Commands::JudgeShadowPairs.new(
+                              shadow_pairs: @graph.shadow_pair_store,
+                              settings_store: @rt.component(:settings_store),
+                              criterion: criterion, event_stream: @graph.event_stream
+                            ))
+      end
+
       def configure_studio
         Studio::App.configure(
           command_bus: @graph.bus, profile_source: @graph.profiles,
@@ -64,16 +90,81 @@ module Insika
           agent_file_store: @rt.component(:agent_file_store), skill_store: @rt.component(:skill_store),
           skill_catalog: @graph.skill_catalog, tool_catalog: @graph.tool_catalog,
           tool_store: @rt.component(:tool_store), memory_store: @graph.memory_store,
+          # the Customers drill renders the audit lines.
+          memory_audit_store: @graph.memory_audit_store,
           session_store: @graph.session_store,
           settings_store: @rt.component(:settings_store), llm_provider_store: @rt.component(:provider_store),
           mcp_store: @rt.component(:mcp_store), system_file_store: @rt.component(:system_file_store),
           tool_trace_store: @rt.component(:tool_trace_store),
           context_trace_store: @rt.component(:context_trace_store),
+          # the per-agent cache-hit series (agent-detail card).
+          cache_series_store: @rt.component(:cache_series_store),
           task_store: @graph.task_store, checkpoint_store: @graph.checkpoint_store,
-          pending_action_store: @graph.pending_action_store
+          pending_action_store: @graph.pending_action_store,
+          # WS7: the agents-grid scorecard reads the outcome store.
+          outcome_store: @graph.outcome_store,
+          # the outcome-funnel page reads the fold's cells and the
+          # BudgetLedger's current counters (D6); the only mutation — the
+          # baseline freeze — dispatches :freeze_funnel_baseline on the bus.
+          funnel_store: @graph.funnel_store,
+          budget_ledger: @graph.budget_ledger,
+          # the parity page (only rendered when a shadow channel exists —
+          # the nav row keys off the registry).
+          shadow_pair_store: @graph.shadow_pair_store,
+          parity_criterion: @builder.criterion,
+          channel_registry: @graph.channel_registry,
+          # the Follow-ups page reads the stores directly;
+          # its only mutations (cancel, force-revoke) dispatch bus commands.
+          followup_store: @graph.followup_store,
+          contact_store: @graph.contact_store,
+          # the Facts (wiki) page reads the proposal store
+          # directly; its mutations dispatch :resolve_proposal on the bus.
+          proposal_store: @graph.proposal_store,
+          # the Harvest page reads the harvest store + the two
+          # pre-registered artifacts directly; its mutations dispatch the
+          # harvest bus commands. The criterion/negative list load best-effort
+          # (nil = the page renders the refusal/empty states).
+          harvest_store: @graph.harvest_store,
+          harvest_criterion: harvest_criterion,
+          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.
+      def harvest_criterion
+        path = Insika::EnvSchema.read("INSIKA_HARVEST_CRITERION")
+        path && Insika::Harvest::Criterion.load(path)
+      rescue Insika::ConfigError, Insika::ValidationError
+        nil
+      end
+
+      def harvest_negative_list
+        path = Insika::EnvSchema.read("INSIKA_HARVEST_NEGATIVE")
+        path && Insika::Harvest::NegativeList.parse(File.read(path))
+      rescue Errno::ENOENT
+        nil
+      end
+
       def persistence
         @graph.durable? ? "durable (sqlite)" : "ephemeral (memory)"
       end

data/lib/insika/dsl/system.rb

@@ -15,13 +15,21 @@ module Insika
     # require the child agents to be resolvable in the SAME ProfileSource. A
     # Definition owns exactly one pack, so those patterns had no home in the DSL.
     class System
-      attr_reader :definitions, :workflows, :runtime_options
+      attr_reader :definitions, :workflows, :mcp_instances, :runtime_options
 
       # `backend`: the store this system's graph owns. nil = the
       # historic path (INSIKA_DB, or memory when unset). Set by `Insika.embed`.
-      def initialize(definitions:, workflows: [], runtime: {}, backend: nil)
+      def initialize(definitions:, workflows: [], mcp_instances: [], runtime: {}, backend: nil)
         @definitions = definitions.freeze
         @workflows = workflows.freeze
+        # MCP instances are global to the graph (one McpStore, not per-agent),
+        # so a system-level `mcp` declaration and one nested inside a member
+        # `agent { … }` block land in the same set. A name declared both places
+        # is NOT an error here (unlike within one collection) — the later one
+        # (system-level, applied last) simply wins; Insika::DSL::Runtime upserts
+        # this combined list once at boot.
+        @mcp_instances = (definitions.flat_map(&:mcp_instances) + mcp_instances)
+                          .each_with_object({}) { |m, acc| acc[m[:name]] = m }.values.freeze
         @backend = backend
         # Agent-level runtime knobs merged in declaration order, then the
         # system-level ones on top (an explicit `provider`/`api_key` in the