insika 0.3.0 → 0.7.0

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,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 +
@@ -288,14 +265,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.

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

data/lib/insika/dsl.rb

@@ -47,6 +47,7 @@ module Insika
       def initialize
         @definitions = []
         @workflows = []
+        @mcp_instances = []
         @runtime = {}
       end
 
@@ -54,7 +55,8 @@ module Insika
         instance_eval(&block) if block
         raise ArgumentError, "Insika.system needs at least one agent" if @definitions.empty?
 
-        System.new(definitions: @definitions, workflows: @workflows, runtime: @runtime, backend: backend)
+        System.new(definitions: @definitions, workflows: @workflows,
+                   mcp_instances: @mcp_instances, runtime: @runtime, backend: backend)
       end
 
       # Declares one agent — the SAME block the standalone `Insika.agent` takes.
@@ -101,6 +103,34 @@ module Insika
       def provider(name) = @runtime[:provider] = name.to_s
       def api_key(value) = @runtime[:api_key] = value.to_s
       def api_base(value) = @runtime[:api_base] = value.to_s
+
+      # Declares an MCP server instance: global to the graph, not
+      # any one agent — gated per agent through `tools_allow_groups` on the
+      # group `mcp:<name>`, same as any other tool group. `Insika::DSL::Runtime`
+      # upserts it into the McpStore at boot; the MOTOR-VS-FORJA rule applies —
+      # code is the TEMPLATE (transport/command/args/url/description always
+      # follow the DSL), but an operator's own `enabled`/`env`/`headers` edit
+      # via Studio/CLI/API, once the instance exists, is never clobbered back.
+      #   mcp "tavily", transport: :http, url: "https://mcp.tavily.com/mcp",
+      #       headers: { "Authorization" => "Bearer #{ENV["TAVILY_KEY"]}" }
+      #   mcp "filesystem", transport: :stdio, command: "npx",
+      #       args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+      #
+      # A SYSTEM-level declaration (as opposed to inside one member `agent { }`
+      # block) has no single agent's config to auto-grant — it does NOT by
+      # itself give any agent access. Declare the `mcp` inside the specific
+      # `agent { }` block that needs it instead, where `Builder#mcp` auto-adds
+      # "mcp:<name>" to THAT agent's `tools_allow_groups` (below).
+      def mcp(name, transport: nil, command: nil, args: nil, url: nil,
+              headers: nil, env: nil, description: nil, enabled: true)
+        n = name.to_s
+        raise ArgumentError, "duplicate mcp instance in system: #{n}" if @mcp_instances.any? { |m| m[:name] == n }
+
+        @mcp_instances << { name: n, transport: transport&.to_s, command: command, args: args,
+                             url: url, headers: headers, env: env, description: description,
+                             enabled: enabled }
+        n
+      end
     end
 
     # Collects the declarations and emits a Insika::Pack. Declarations map 1:1 to
@@ -117,11 +147,12 @@ module Insika
         # correct once you restrict tools/skills. Visible in #to_pack — no hidden magic.
         @config[:policies] = %i[tool_allowlist skill_allowlist]
         @runtime = {} # non-pack knobs (llm provider/key/base) consumed by the runtime
+        @mcp_instances = []
       end
 
       def build(&block)
         instance_eval(&block) if block
-        Definition.new(pack: to_pack, runtime: @runtime)
+        Definition.new(pack: to_pack, runtime: @runtime, mcp_instances: @mcp_instances)
       end
 
       # --- identity & model ------------------------------------------------
@@ -204,6 +235,34 @@ module Insika
         @config[:subagents] = ids.flatten.map(&:to_s)
       end
 
+      # --- mcp ---------------------------------------------------------------
+      # Declares an MCP server instance — see
+      # Insika::DSL::SystemBuilder#mcp for the transport/lifecycle doc; identical
+      # shape here for a standalone `Insika.agent { … }` script, or one member
+      # agent of a system, that wants one.
+      #
+      # Auto-adds "mcp:<name>" to THIS agent's `tools_allow_groups` — without
+      # it, a pack with no `data_tool` gets PackImporter's `tools_allow: []`
+      # (isolation default) and no `tools_allow_groups` at all, so
+      # Policy::ToolAllowlist#allowed_names resolves an EMPTY allowlist and the
+      # agent could never call the MCP tool it just declared (found writing the
+      # MCP templates — no existing spec exercised this path end to
+      # end). Same "auto-added to the allowlist" contract `data_tool` already
+      # gives its own tool name; `deny_tools` has no group-string equivalent
+      # yet, so a whole MCP group cannot be denied by name today.
+      def mcp(name, transport: nil, command: nil, args: nil, url: nil,
+              headers: nil, env: nil, description: nil, enabled: true)
+        n = name.to_s
+        raise ArgumentError, "duplicate mcp instance in agent: #{n}" if @mcp_instances.any? { |m| m[:name] == n }
+
+        @mcp_instances << { name: n, transport: transport&.to_s, command: command, args: args,
+                             url: url, headers: headers, env: env, description: description,
+                             enabled: enabled }
+        group = "mcp:#{n}"
+        (@config[:tools_allow_groups] ||= []) << group unless Array(@config[:tools_allow_groups]).include?(group)
+        n
+      end
+
       # --- knobs -----------------------------------------------------------
       def memory(on = true) = @config[:memory] = on
 
@@ -255,6 +314,41 @@ module Insika
       #           miner: { model: "deepseek-v4-flash", window: { last_sessions: 200 } }
       def harvest(hash) = (@config[:harvest] ||= {}).merge!(hash.transform_keys(&:to_s))
 
+      # The post-turn knowledge declaration: after a turn completes, the
+      # engine may extract durable CONCEPTS (facts, procedures, policies,
+      # objections) from it and persist them for later turns to retrieve.
+      # Pack data — merges, so repeated calls accumulate (like budget).
+      # `prompt`/`model` are pack-authored keys the DSL passes through.
+      #   knowledge extract: true, retrieve: true, types: %w[fact policy]
+      def knowledge(hash) = (@config[:knowledge] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # A recurring schedule: one declaration per call,
+      # named — a turn the ENGINE fires on its own tick, nobody has to
+      # remember. `cron` (5 fields) or `every` (plain interval), a tz for
+      # cron materialization, the synthetic inbound `message` that kicks each
+      # run, a session mode (`new` = a fresh session per run — the report
+      # case; `fixed` = one standing session), per-run `overrides`
+      # (turn_timeout / max_tool_calls / model) and `enabled`.
+      #   schedule "daily_report", cron: "0 22 * * *", tz: "America/Sao_Paulo",
+      #            message: "Run the daily report now.",
+      #            overrides: { turn_timeout: 900, max_tool_calls: 200 }
+      # Distinct by shape from the `schedule_followup` TOOL (a one-shot,
+      # customer-facing, consent-gated contact); see docs/SCHEDULING.md.
+      def schedule(name, every: nil, cron: nil, tz: nil, message: nil,
+                   session_mode: nil, session_id: nil, overrides: nil, enabled: nil)
+        id = name.to_s.downcase # the engine canonicalizes ids to lowercase
+        if Array(@config[:schedules]).any? { |s| s["id"] == id }
+          raise ArgumentError, "duplicate schedule in agent: #{id}"
+        end
+
+        entry = { "id" => id, "every" => every, "cron" => cron, "tz" => tz,
+                  "message" => message, "session_mode" => session_mode,
+                  "session_id" => session_id, "overrides" => overrides,
+                  "enabled" => enabled }.compact
+        @config[:schedules] = Array(@config[:schedules]) + [entry]
+        id
+      end
+
       # Provider-interaction reliability, as DATA (WS3): retries + exponential
       # backoff on transient failures, a fallback model chain (mid-turn
       # rotation), and a circuit breaker per (tenant, provider/model) that
@@ -305,6 +399,13 @@ module Insika
       #           tts:   { model: "tts-1", voice: "alloy" }
       def outputs(hash) = (@config[:outputs] ||= {}).merge!(hash.transform_keys(&:to_s))
 
+      # STT vocabulary hint (WS9): domain words (product names, brand terms)
+      # the transcriber should expect on THIS agent's voice notes — passed
+      # straight through to the Whisper-family provider's `prompt:`. Falls
+      # back to INSIKA_STT_PROMPT (deployment default) when unset.
+      #   stt_prompt "Ocean Drop, tênis, boné trucker, chinelo"
+      def stt_prompt(text) = @config[:stt_prompt] = text.to_s
+
       # The engine's "Tool discipline" block in the system prompt (retry a
       # weak/empty tool result with a different approach before giving up).
       # ON by default — this setter exists to turn it OFF:

data/lib/insika/env_schema.rb

@@ -110,6 +110,9 @@ module Insika
       spec(name: "INSIKA_TURN_TIMING", type: :boolean, description: "Emit per-turn TTFB breakdown in responses (opt-in)."),
       spec(name: "INSIKA_SUBAGENT_DEPTH_CAP", type: :integer, description: "Max delegation depth in the subagent graph (default 5)."),
       spec(name: "INSIKA_SUBAGENT_FANOUT_CAP", type: :integer, description: "Max parallel children in spawn_subagents (default 8)."),
+      spec(name: "INSIKA_ARTIFACT_SIGNING_KEY", secret: true, description: "HMAC key for signed artifact links (INSIKA_ARTIFACT_SIGNING_TTL). Unset -> no signed artifact surface."),
+      spec(name: "INSIKA_ARTIFACT_SIGNING_TTL", type: :integer, description: "Seconds a signed artifact link stays valid (default 604800 = 7 days)."),
+      spec(name: "INSIKA_ARTIFACT_MAX_BYTES", type: :integer, description: "Size cap on an artifact's content in bytes (default 1048576)."),
       spec(name: "INSIKA_CONFIG_STRICT", type: :boolean, description: "Refuse boot on any config finding instead of warning."),
       spec(name: "INSIKA_BOOT_ID", description: "Boot generation id shared by all workers of one container start; the recovery task sweep runs once per id. Unset -> every boot sweeps."),
       spec(name: "INSIKA_DRAIN_TIMEOUT", type: :integer, description: "Seconds a stopping worker waits for in-flight turns before abandoning them to the next boot's recovery (default 20)."),
@@ -117,6 +120,7 @@ module Insika
       spec(name: "INSIKA_TICK_STALE_AFTER", type: :integer, description: "Seconds a :queued/:running task must sit untouched before the tick sweeps it (default 900). Must exceed the largest turn_timeout of the deployment."),
       spec(name: "INSIKA_STT_MODEL", description: "Model used to transcribe audio message parts (WS9). Unset -> RubyLLM's default transcription model."),
       spec(name: "INSIKA_STT_LANGUAGE", description: "Language hint for the transcription of audio message parts (WS9)."),
+      spec(name: "INSIKA_STT_PROMPT", description: "Deployment-wide vocabulary hint (product names, brand terms) for audio transcription (WS9). Overridden per agent by the profile's stt_prompt."),
       spec(name: "INSIKA_TENANCY", enum: %w[single_tenant multi_tenant], description: "single_tenant (default: one operator credential) or multi_tenant (per-tenant + operator tokens resolved from the store)."),
       spec(name: "INSIKA_ONBOARDING", type: :boolean, description: "Expose the public onboarding surface (/start.md, /models.json, /docs) in production (opt-in)."),
       spec(name: "INSIKA_RELAY_TOKEN", secret: true, description: "Bearer the relay consumer sends us. Unset -> the relay channel is not mounted."),
@@ -129,9 +133,20 @@ module Insika
       spec(name: "INSIKA_HARVEST_NEGATIVE", type: :path, description: "The negative-list seed file the harvest CLI imports into agent profiles."),
       spec(name: "INSIKA_WIDGET_ORIGINS", type: :csv, description: "Exact-match origins allowed to embed the web widget. Unset -> the widget channel is not mounted."),
       spec(name: "INSIKA_WIDGET_AGENTS", type: :csv, description: "Agent ids a widget visitor may address. Unset -> the widget channel is not mounted."),
+      spec(name: "INSIKA_MCP_STDIO", type: :boolean, description: "Allow stdio MCP instances to spawn a child process (arbitrary command execution by config). Unset -> stdio instances save but refuse to start."),
+      spec(name: "INSIKA_ROUTER_BACKENDS", type: :csv, description: "comma-separated backend URLs for `insika-router` (static discovery, the Railway shape). Exactly one of this or INSIKA_ROUTER_BACKENDS_DNS."),
+      spec(name: "INSIKA_ROUTER_BACKENDS_DNS", description: "a headless-Service hostname `insika-router` re-resolves on an interval (the Kubernetes shape). Requires INSIKA_ROUTER_BACKEND_PORT."),
+      spec(name: "INSIKA_ROUTER_BACKEND_PORT", type: :integer, description: "the engine port on every DNS-resolved backend pod (required with INSIKA_ROUTER_BACKENDS_DNS)."),
+      spec(name: "INSIKA_ROUTER_DNS_INTERVAL", type: :integer, description: "seconds between `insika-router` DNS re-resolves (default 15)."),
+      spec(name: "INSIKA_ROUTER_BODY_MAX_BYTES", type: :integer, description: "size cap `insika-router` will parse looking for a session key before falling back to round-robin (default 262144; never bounds what is forwarded)."),
+      spec(name: "INSIKA_ROUTER_BACKEND_TIMEOUT", type: :integer, description: "`insika-router`'s connect/read timeout to a backend, in seconds (default 10)."),
+      spec(name: "INSIKA_ROUTER_HOST", description: "bind address for `insika-router` itself (default 0.0.0.0)."),
+      spec(name: "INSIKA_ROUTER_PORT", type: :integer, description: "listen port for `insika-router` itself (default 9090)."),
       spec(name: "OPENCLAW_GATEWAY_TOKEN", secret: true, description: "Bearer for /v1 + /a2a (falls back to ADMIN_TOKEN)."),
       spec(name: "OPENCLAW_AGENTS_DIR", type: :path, description: "Directory of OpenClaw-style agent packs."),
-      spec(name: "OPENCLAW_PLUGIN_DIR", type: :path, description: "Directory of plugins to load."),
+      spec(name: "INSIKA_PLUGIN_DIR", type: :path, description: "Workspace plugin root (directories with insika.plugin.yml). Loaded at boot; ids still need INSIKA_PLUGINS."),
+      spec(name: "INSIKA_PLUGINS", type: :csv, description: "Plugin ids to enable from the workspace/bundled roots. Announced gems are enabled by installing them."),
+      spec(name: "INSIKA_PLUGINS_DISABLED", type: :csv, description: "Plugin ids that never load — the absolute veto, wins over INSIKA_PLUGINS and over an announced gem."),
       spec(name: "ADMIN_TOKEN", secret: true, description: "Studio login token; unset -> /studio fail-closed."),
       spec(name: "OTEL_SERVICE_NAME", description: "Service name for OTEL spans (default: insika).")
     ].freeze

data/lib/insika/evals/golden.rb

@@ -11,10 +11,26 @@ module Insika
   module Evals
     # A curated behavior case, loaded from a data file (evals/golden/<agent>/*.yml).
     # Data, not code — same spirit as tools-as-data. See evals/README.md for the format.
-    Golden = Struct.new(:id, :agent, :turns, :expect, :requires, :reference, :source, keyword_init: true) do
-      # The user messages to replay, in order.
+    #
+    # A case is ONE of two shapes: `turns:` (a scripted replay) or
+    # `persona:` (a conversation the Simulator GENERATES). A persona
+    # case is `simulated?` — the replay Runner skips it, and the Simulator drives it.
+    #
+    # `tenant` (C3.1): which tenant authored this case — "platform" (the
+    # single-tenant default, like `save_artifact`'s own binding_tenant) unless the
+    # case declares one. `run_persona_eval` uses it to keep a QA agent from ever
+    # running (or even seeing) another tenant's persona case in the same store.
+    Golden = Struct.new(:id, :agent, :turns, :expect, :requires, :reference, :source, :persona, :tenant,
+                        keyword_init: true) do
+      # The user messages to replay, in order. Empty for a persona case: a generated
+      # conversation has no scripted turns.
       def user_turns = turns.map { |t| t["user"] }
 
+      # The simulated customer. nil for a scripted case.
+      def simulated? = !persona.nil?
+
+      def opens_with = persona ? persona.opens_with : user_turns.first
+
       # Tool refs the case expects; a trailing "?" marks OPTIONAL (never fails).
       # -> [{ name:, optional: }]
       def tools_called
@@ -85,7 +101,12 @@ module Insika
 
         id = presence(raw["id"]) || (raise InvalidGolden, "#{source}: 'id' is required")
         agent = presence(raw["agent"]) || (raise InvalidGolden, "#{source}: 'agent' is required (case '#{id}')")
-        turns = normalize_turns(raw["turns"], id: id, source: source)
+        persona = normalize_persona(raw["persona"], id: id, source: source)
+        if persona && !raw["turns"].nil?
+          raise InvalidGolden, "#{source}: a case is ONE shape — 'turns' or 'persona', not both (case '#{id}')"
+        end
+
+        turns = persona ? [] : normalize_turns(raw["turns"], id: id, source: source)
         expect = raw["expect"] || {}
         raise InvalidGolden, "#{source}: 'expect' must be a mapping (case '#{id}')" unless expect.is_a?(Hash)
 
@@ -96,9 +117,25 @@ module Insika
         end
 
         reference = normalize_reference(raw["reference"], id: id, source: source)
+        tenant = presence(raw["tenant"]) || "platform"
 
         Golden.new(id: id, agent: agent, turns: turns, expect: expect,
-                   requires: requires, reference: reference, source: source)
+                   requires: requires, reference: reference, source: source, persona: persona,
+                   tenant: tenant)
+      end
+
+      # `persona:` is the alternative shape to `turns:`: the
+      # conversation is GENERATED, not replayed. Malformed is REFUSED — a persona
+      # without `knows` or `max_turns` would simulate nothing. The PersonaLoader
+      # already prefixes its messages with the source path; the case id is added
+      # ONCE here (the loader is shared by the persona-file CLI, which has no case
+      # shape).
+      def normalize_persona(raw, id:, source:)
+        return nil if raw.nil?
+
+        PersonaLoader.build(raw, source: source)
+      rescue PersonaLoader::InvalidPersona => e
+        raise InvalidGolden, "#{e.message} (case '#{id}')"
       end
 
       # reference: { "source" => String?, "messages" => [{ "role" =>, "text" =>,

data/lib/insika/evals/judge.rb

@@ -67,7 +67,28 @@ module Insika
         return nil if rubric.empty?
 
         prompt = build_prompt(rubric, golden.user_turns, result.output_text.to_s, golden.policy)
-        min = golden.min_score || DEFAULT_MIN_SCORE
+        score_prompt(prompt, golden.min_score || DEFAULT_MIN_SCORE)
+      end
+
+      # A whole CONVERSATION (a simulated run) scored against the
+      # rubric — the transcript, not its last turn. `transcript` is
+      # [{ role: "user"|"assistant", text: }] in order. -> Verdict, or nil without
+      # a rubric. Same panel, same rules as `score`: the rubric that scores a
+      # scripted replay scores a generated one.
+      def score_conversation(rubric:, transcript:, policy: nil, min_score: DEFAULT_MIN_SCORE)
+        rubric = rubric.to_s.strip
+        return nil if rubric.empty?
+
+        prompt = conversation_prompt(rubric, transcript, policy)
+        score_prompt(prompt, min_score)
+      end
+
+      private
+
+      # The panel machinery shared by `score` (a single reply) and
+      # `score_conversation` (a generated transcript): ask each judge, combine,
+      # decide by min_agreement. -> Verdict.
+      def score_prompt(prompt, min)
         panel = @asks.map { |ask| judge_once(ask, prompt, min) }
 
         agreed = panel.count { |j| j[:pass] }
@@ -77,7 +98,31 @@ module Insika
                     judges: panel.map { |j| j[:score] })
       end
 
-      private
+      # The judge reads the FULL conversation as the customer lived it — every
+      # user turn and every assistant reply interleaved. A rubric about the whole
+      # exchange ("does it discover the objective before recommending?") is
+      # unanswerable from the last reply alone.
+      def conversation_prompt(rubric, transcript, policy)
+        lines = Array(transcript).map do |m|
+          role = m[:role].to_s == "user" ? "customer" : "assistant"
+          "#{role}: #{m[:text].to_s.strip}"
+        end.join("\n")
+        <<~PROMPT
+          You are a strict QA judge for a customer-service AI assistant. Judge the
+          ASSISTANT'S HANDLING OF THE WHOLE CONVERSATION against the RUBRIC — nothing
+          else.
+
+          RUBRIC:
+          #{rubric}
+          #{policy_clause(policy)}
+          CONVERSATION (in order):
+          #{lines}
+
+          Score from 0.0 (fails the rubric) to 1.0 (fully meets it). Respond with ONLY a
+          JSON object, no prose:
+          {"score": <0..1>, "reason": "<one short sentence>"}
+        PROMPT
+      end
 
       # One model's verdict: its own samples, its own median, its own pass/fail.
       def judge_once(ask, prompt, min)

data/lib/insika/evals/pairwise.rb

@@ -84,6 +84,17 @@ module Insika
         end.flatten.join("\n")
       end
 
+      # A GENERATED (simulated) conversation as the judge reads it: the transcript
+      # is already interleaved [{ role: "user"|"assistant", text: }] — map it to the
+      # same customer/assistant lines a replay produces, so pairwise compares like
+      # for like (a simulated run can be compared against the incumbent).
+      def self.transcript_text(messages)
+        Array(messages).map do |m|
+          role = m[:role].to_s == "user" ? "customer" : "assistant"
+          "#{role}: #{m[:text].to_s.strip}"
+        end.join("\n")
+      end
+
       # The incumbent's half. Human turns are NOT flagged to the judge: what it grades
       # is the conversation as the customer received it, and telling it "a person wrote
       # this one" is an invitation to grade the author instead. The fact is carried to