insika 0.2.0 → 0.7.0

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
 
@@ -215,6 +274,81 @@ module Insika
       #   budget daily: 100_000, monthly: 2_000_000, soft: false
       def budget(hash) = (@config[:budget] ||= {}).merge!(hash.transform_keys(&:to_s))
 
+      # The outcome funnel declaration: the store's stage vocabulary
+      # as pack data — the engine folds WS7 outcome kinds into the DECLARED
+      # stages, and never hard-codes one itself. Merges, so repeated calls
+      # accumulate (like budget).
+      #   funnel stages: %w[greeted qualified cart paid],
+      #          advance_on: { "pix_paid" => "paid", "abandoned_cart" => "cart" },
+      #          primary: "paid", attribution_window: "72h"
+      def funnel(hash) = (@config[:funnel] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The follow-up declaration: the agent may book a follow-up
+      # with a customer at a future time (`schedule` tool); the engine fires the
+      # synthetic turn and enforces the policy (quiet hours, max frequency,
+      # cancellation keywords, silence detection) at fire time. Pack data —
+      # merges, so repeated calls accumulate (like budget).
+      #   followup arm: "schedule",
+      #            policy: { quiet_hours: { timezone: "America/Sao_Paulo",
+      #                                     start: "21:30", end: "09:00" },
+      #                      max_frequency: "2/24h",
+      #                      cancel_keywords: ["não quero mais contato"],
+      #                      silence_after_sends: 3 }
+      def followup(hash) = (@config[:followup] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The session-distillation declaration: what counts as a fact
+      # for THIS store, distilled from finished customer conversations. Pack
+      # data — merges, so repeated calls accumulate (like budget). `prompt` and
+      # `model` are pack-authored keys the DSL passes through.
+      #   distill enabled: true, idle_hours: 6, max_proposals: 10
+      def distill(hash) = (@config[:distill] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The gated-harvest declaration: the engine may read this
+      # agent's finished traffic and propose SKILLS for the store's playbook —
+      # through the negative list, the grounding filter and the double gate,
+      # never applied automatically. Pack data — merges, so repeated calls
+      # accumulate (like budget). `prompt`/`model` are pack-authored keys the
+      # DSL passes through.
+      #   harvest enabled: true,
+      #           negative_list: [ { rule: "no-competitor-prices", pattern: "concorrente" } ],
+      #           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
@@ -226,17 +360,58 @@ module Insika
         (@config[:reliability] ||= {}).merge!(hash.transform_keys(&:to_s))
       end
 
-      # Operator alert delivery (WS6): POST this agent's budget_warning /
-      # breaker_open / delivery_failed events to the webhook, as JSON.
-      #   alerts webhook: "https://ops.example.com/insika-alerts"
+# Operator alert delivery (WS6): POST this agent's budget_warning /
+      # breaker_open / delivery_failed events to the webhook as JSON.
       def alerts(hash) = (@config[:alerts] ||= {}).merge!(hash.transform_keys(&:to_s))
 
+      # Intent routing (WS4): classify each turn's message into one route with a
+      # cheap model BEFORE the ask. A Hash: route name -> description (or a Hash
+      # with description/delegate/stuck/message), plus the reserved keys
+      # "default" (the deterministic fallback) and "model"/"provider" (the cheap
+      # classifier). The classifier prompt is generated — data only.
+      #   routes "shopping" => "the customer wants to browse products",
+      #          "order"    => { "description" => "asks about an existing order",
+      #                          "delegate" => "order-agent" },
+      #          "human"    => { "description" => "the customer asks for a person",
+      #                          "stuck" => true },
+      #          "default"  => "shopping", "model" => "deepseek-v4-flash"
+      def routes(hash) = (@config[:routes] ||= {}).merge!(hash.transform_keys(&:to_s))
+
       # The agent may signal it cannot proceed (WS5): when on, the model
       # can call `signal_stuck`, which ends the turn with `outcome: :stuck` + a final
       # message + a `:turn_stuck` event. What "stuck" means is the consumer's call.
       #   stuck_signal true
       def stuck_signal(on = true) = @config[:stuck_signal] = on
 
+      # The per-session working-state schema this agent keeps and asks for
+      # a flat list of field names. [] = off (no provider output,
+      # no update_briefing/set_next_step tools).
+      #   briefing_fields "size", "budget", "delivery_day"
+      def briefing_fields(*names)
+        @config[:briefing_fields] = names.flatten.map(&:to_s)
+      end
+
+      # Generated-media output policy (WS9, saída): the media kinds this
+      # agent MAY generate as turn outputs, with per-kind config. The other
+      # half of the gate is the CHANNEL's: the request must declare the
+      # matching capability for the tools to exist at all.
+      #   outputs image: { model: "gpt-image-1", size: "1024x1024" },
+      #           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:
+      #   tool_persistence false
+      def tool_persistence(on = true) = @config[:tool_persistence] = on
+
       # Mechanical tool-result dedupe in the replayed history
       # (no-LLM compaction, apt for bloated transcripts). CHANGES WHAT THE MODEL
       # SEES: repeated identical tool results collapse to a back-reference.
@@ -250,6 +425,12 @@ module Insika
       #              responses: { "injection" => "I can't help with that." }
       def guardrails(hash) = (@config[:guardrails] ||= {}).merge!(hash.transform_keys(&:to_s))
 
+      # Evidence-grounding policy: the pack declares how the engine
+      # polices product claims against the evidence ledger. Same
+      # config-over-code shape as `guardrails`; absent = off (parity).
+      #   grounding mode: :flag, matcher: { sku: '\b[A-Z]{2,4}\d{4,8}\b' }
+      def grounding(hash = {}) = (@config[:grounding] ||= {}).merge!(hash.transform_keys(&:to_s))
+
       # Refinement — how the agent's own instruction files may be
       # improved from real traffic. Same config-over-code shape as `guardrails`;
       # omitting it entirely leaves the agent report-only (writes nothing).

data/lib/insika/edge_limiter.rb

@@ -65,8 +65,14 @@ module Insika
       # the rate-limit reply exactly when the window is saturated. Entry checks
       # are skipped; the turn's usage still lands on the ledger below.
       resumed = state.resumed
-
-      if !resumed && (limit = positive(limits.key?(:chat_rate_limit) ? limits[:chat_rate_limit] : edge["chat_rate_limit"]))
+      # a SCHEDULED turn (the FollowupEngine's kick) skips the
+      # ENTRY checks exactly like a resume — a follow-up that trips the token
+      # ceiling must not receive the rate-limit REPLY (the customer agreed to
+      # this message; the volume control is the follow-up policy, not the flood
+      # rail). The turn still runs and its usage still lands on the ledger.
+      scheduled = scheduled_turn?(state)
+
+      if !resumed && !scheduled && (limit = positive(limits.key?(:chat_rate_limit) ? limits[:chat_rate_limit] : edge["chat_rate_limit"]))
         breach = check_chat_rate(state, limit, edge)
         return block(state, edge, **breach) if breach
       end
@@ -75,7 +81,7 @@ module Insika
       # `"chat_rate_limit": null`) reads as OFF for that agent, not "inherit".
       if (ceiling = positive(limits.key?(:agent_token_ceiling) ? limits[:agent_token_ceiling] : edge["agent_token_ceiling"]))
         token_window = positive(edge["agent_token_window"]) || DEFAULT_TOKEN_WINDOW
-        unless resumed
+        unless resumed || scheduled
           spent = @ledger.count(TOKENS_KIND, state.profile.id.to_s, window: token_window)
           if spent >= ceiling
             return block(state, edge, category: :token_ceiling,
@@ -90,9 +96,11 @@ module Insika
       # typed error (never a customer-facing reply); the alert_at warning and
       # the SOFT over-cap both warn once per window + inject a context note.
       # A resumed turn (crash/pause replay) was already admitted: it is never
-      # refused twice — its spend still lands on the ledger below.
+      # refused twice — its spend still lands on the ledger below. A scheduled
+      # turn  rides the same rule: the follow-up policy is the
+      # volume control, not the budget wall.
       budget_on = budget_configured?(state)
-      budget_enforce(state) unless resumed
+      budget_enforce(state) unless resumed || scheduled
 
       result = begin
         nxt.call(state)
@@ -110,6 +118,14 @@ module Insika
 
     private
 
+    # is this turn the FollowupEngine's synthetic kick? The
+    # command type is stamped by the engine only — a consumer cannot send it
+    # (the SendMessage edge refuses the spelling, C8).
+    def scheduled_turn?(state)
+      command = state.respond_to?(:task) && state.task&.command
+      command.is_a?(Hash) && command["type"].to_s == "scheduled_followup"
+    end
+
     # One KV get per turn (same order of cost as the guardrail's config read);
     # no SettingsStore in the wiring -> per-agent limits only.
     def platform_edge
@@ -231,12 +247,17 @@ module Insika
       return if @budget_ledger.mark_alert(tenant: tenant, agent: agent, window: w[:window],
                                           level: level, now: now)
 
+      # `tenant` on the META too, not only in the payload: the tenant-scoped
+      # /v1/events subscription filters on meta[:tenant] and is fail-closed, so
+      # a warning about the tenant's OWN budget never reached the tenant.
+      meta = { task_id: state.task&.id, session_id: state.task&.session_id,
+               at: Time.now.utc.iso8601 }
+      meta[:tenant] = tenant unless tenant.nil?
       @event_stream&.emit(Insika::Event.new(
                             type: :budget_warning,
                             data: { agent: agent, tenant: tenant, window: w[:window],
                                     spent: spent, cap: w[:cap], level: level },
-                            meta: { task_id: state.task&.id, session_id: state.task&.session_id,
-                                    at: Time.now.utc.iso8601 }
+                            meta: meta
                           ))
     end
 

data/lib/insika/env_schema.rb

@@ -102,29 +102,51 @@ module Insika
       spec(name: "INSIKA_ENV", description: "Environment name shown in the Studio (falls back to RACK_ENV)."),
       spec(name: "INSIKA_A2A_AGENT", description: "Agent id to expose over inbound A2A (opt-in)."),
       spec(name: "INSIKA_A2A_REMOTES", type: :csv, description: "Comma-separated remote A2A endpoints."),
-      spec(name: "INSIKA_EGRESS_ALLOW_HTTP", type: :boolean, description: "Allow plain http egress from data-tools (default: https only)."),
+      spec(name: "INSIKA_EGRESS_ALLOW_HTTP", type: :boolean, description: "Allow plain http egress from data-tools, channel callbacks and media fetches (default: https only)."),
       spec(name: "INSIKA_EGRESS_ALLOW_PRIVATE", type: :boolean, description: "Allow egress to private/loopback ranges (SSRF guard off)."),
-      spec(name: "INSIKA_EGRESS_HOSTS", type: :csv, description: "Comma-separated host allowlist for data-tool egress."),
+      spec(name: "INSIKA_EGRESS_HOSTS", type: :csv, description: "Comma-separated host allowlist for data-tool egress (media fetches are NOT pinned by it)."),
       spec(name: "INSIKA_OTEL", type: :boolean, description: "Turn on OpenTelemetry export (opt-in)."),
       spec(name: "INSIKA_MODEL_PRICING", description: "JSON rates table (USD per million tokens) for the estimated-cost attribute; unset -> no cost reported."),
       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)."),
       spec(name: "INSIKA_TICK_INTERVAL", type: :integer, description: "Seconds between tick passes (outbox drain + stale recovery sweep). Default 60; 0 disables."),
       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."),
       spec(name: "INSIKA_RELAY_DELIVER_URL", type: :url, description: "Consumer callback the relay POSTs each reply to."),
       spec(name: "INSIKA_RELAY_DELIVER_TOKEN", secret: true, description: "Bearer the relay sends TO the consumer's callback (optional)."),
+      spec(name: "INSIKA_RELAY_SHADOW", type: :boolean, description: "Shadow mode: the relay records replies instead of delivering them."),
+      spec(name: "INSIKA_RELAY_DELIVERY", type: :enum, enum: %w[at_end progressive], description: "How the relay flushes the outbox: at_end (one POST) or progressive (one POST per balloon). Unset -> at_end."),
+      spec(name: "INSIKA_PARITY_CRITERION", type: :path, description: "The frozen parity criterion file (required in shadow mode)."),
+      spec(name: "INSIKA_HARVEST_CRITERION", type: :path, description: "The frozen harvest conversion criterion file (strict-loaded before any promotion)."),
+      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/errors.rb

@@ -182,6 +182,17 @@ module Insika
   # tell "the recipient refused" from "the engine has a bug".
   class DeliveryError < Error; end
 
+  # WS4 routing failed: a route's delegate agent is not configured, or its turn
+  # failed. An operator/config error — the envelope names the :routing stage
+  # instead of swallowing it as :unknown.
+  class RoutingError < Error; end
+
+  # WS9 media failed: an audio part could not be fetched or transcribed, an
+  # image attachment could not be built, or a media URL was egress-blocked. A
+  # customer's voice message that never entered the turn must not be silently
+  # dropped — the :media stage names it.
+  class MediaError < Error; end
+
   # Strict configuration violation (— OpenClaw's config discipline:
   # "recusa boot com chave desconhecida, no silent config compat"). Raised by
   # EnvSchema.enforce! at boot ONLY when strictness is on (INSIKA_CONFIG_STRICT) —

data/lib/insika/evals/assertions.rb

@@ -59,8 +59,9 @@ module Insika
     module Assertions
       # Named negative detectors for `must_not` now live in the runtime. Kept as
       # an alias so any external reference to Evals::Assertions::PII_DETECTORS still
-      # resolves; the values ARE the runtime's, never a fork.
-      PII_DETECTORS = Insika::Safety::Detectors::PII
+      # resolves; the values ARE the runtime's, never a fork. the
+      # pattern data moved to the corpus, still under the same Safety umbrella.
+      PII_DETECTORS = Insika::Safety::Corpus::PII
 
       # HOW MUCH THE AGENT SHOULD ASK BEFORE ACTING. Declared per
       # case because it is a per-STORE decision, not a universal rule: sometimes the

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

@@ -60,12 +60,19 @@ module Insika
       def compare(golden:, turns:)
         return nil unless golden.reference?
 
-        ours = Pairwise.transcript(golden.user_turns, turns)
-        theirs = Pairwise.reference_transcript(golden.reference_messages)
-        return nil if ours.strip.empty?
+        compare_texts(ours: Pairwise.transcript(golden.user_turns, turns),
+                      theirs: Pairwise.reference_transcript(golden.reference_messages),
+                      vs: golden.human_assisted? ? "human-assisted" : "agent")
+      end
+
+      # two transcripts, no golden — the shadow seam. The judge is
+      # the SAME object with the SAME prompt, so shadow pairs and golden cases are
+      # graded by one rule. An empty side returns nil (never a verdict against an
+      # empty string — that was a bug in the golden path until this seam landed).
+      def compare_texts(ours:, theirs:, vs: "agent")
+        return nil if ours.to_s.strip.empty? || theirs.to_s.strip.empty?
 
-        panel = @asks.map { |ask| judge_once(ask, ours, theirs) }
-        combine(panel, vs: golden.human_assisted? ? "human-assisted" : "agent")
+        combine(@asks.map { |ask| judge_once(ask, ours, theirs) }, vs: vs)
       end
 
       # The replayed conversation as the judge reads it: the user turns we sent,
@@ -77,12 +84,28 @@ 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
       # the READER as `vs: human-assisted` instead, which is where it changes a decision.
+      # A reference with no text at all returns "" — the caller's empty guard then
+      # refuses instead of judging against an empty string .
       def self.reference_transcript(messages)
-        Array(messages).map do |m|
+        msgs = Array(messages)
+        return "" if msgs.all? { |m| m["text"].to_s.strip.empty? }
+
+        msgs.map do |m|
           speaker = m["role"].to_s == "user" ? "customer" : "assistant"
           "#{speaker}: #{m['text'].to_s.strip}"
         end.join("\n")