insika 0.3.0 → 0.8.0

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

@@ -72,10 +72,10 @@ module Insika
 
     # Prefixes the engine fully OWNS: an unknown key under one of these is a typo, not
     # a foreign var. INSIKA_ (current) and HARNESS_ (legacy, still honored during the
-    # deprecation window). Deliberately NOT OPENCLAW_ (shared with the OpenClaw gateway
-    # product, which sets its own OPENCLAW_HOME/_STATE_DIR/… — the engine merely borrows
-    # 3 names for interop), nor LITESTREAM_ (the sidecar owns it), nor OTEL_ (the
-    # OpenTelemetry SDK owns its env).
+    # deprecation window). Deliberately NOT OPENCLAW_ (the OpenClaw gateway product
+    # sets its own OPENCLAW_HOME/_STATE_DIR/… on the same host; the engine reads none
+    # of them), nor LITESTREAM_ (the sidecar owns it), nor OTEL_ (the OpenTelemetry
+    # SDK owns its env).
     OWNED_PREFIXES = [PREFIX, LEGACY_PREFIX].freeze
 
     BOOLEANS = %w[1 0 true false yes no on off].freeze
@@ -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,19 @@ 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: "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_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: "INSIKA_GATEWAY_TOKEN", secret: true, description: "Bearer for /v1 + /a2a (falls back to ADMIN_TOKEN when unset)."),
+      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

data/lib/insika/evals/persona.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Insika
+  module Evals
+    # A SIMULATED CUSTOMER — the data that turns a scripted case into a
+    # generated conversation. Pure data: goal, style, the opening
+    # message, the ONLY facts the persona may assert, and a hard turn cap. The
+    # persona is played by a model (the cheap utility_model) with this as its whole
+    # instruction; the anti-invention rule below is the soul of the feature — a
+    # simulator that invents an order number produces a conversation the agent
+    # could never have had, and a case that tests nothing.
+    Persona = Struct.new(:goal, :style, :opens_with, :knows, :max_turns, keyword_init: true) do
+      def to_h
+        { "goal" => goal, "style" => style, "opens_with" => opens_with,
+          "knows" => knows, "max_turns" => max_turns }.compact
+      end
+
+      # The persona as a whole instruction. The `knows` facts are the ONLY
+      # assertions the persona may make; anything else is answered with
+      # ignorance — "não sei", "não tenho isso aqui" — exactly like a real
+      # customer who does not have the fact. `transcript` is the conversation
+      # so far, in order, as [{ role: "user"|"assistant", text: }].
+      def prompt(transcript)
+        facts = knows.map { |k, v| "- #{k}: #{v}" }.join("\n")
+        <<~PROMPT
+          You are simulating a customer in a chat with a store's virtual assistant.
+          Stay in character. You are not helping the assistant; you are the person
+          it serves.
+
+          GOAL: #{goal}
+          STYLE: #{style || "short, natural messages; answers what is asked"}
+
+          FACTS YOU KNOW — the ONLY facts you may assert:
+          #{facts}
+
+          RULES:
+          1. You may ONLY assert the facts above. Asked about anything else, you do
+             not know it — answer with ignorance, like a real customer without that
+             fact (you have no order number, no name, no date, no price beyond the
+             facts above). Never invent an order number, a name, a date, a price or
+             any other detail that is not in FACTS YOU KNOW.
+          2. Reply with ONLY the customer's next message.
+          3. When your goal has been met, end the message with the marker
+             <<goal_met>>. When you give up (the assistant cannot get you there),
+             end the message with the marker <<gave_up>>. Otherwise end with no
+             marker.
+
+          CONVERSATION SO FAR:
+          #{transcript.map { |m| "#{m[:role]}: #{m[:text]}" }.join("\n")}
+
+          Your next message:
+        PROMPT
+      end
+    end
+
+    # Loads + validates a persona mapping (the `persona:` key of a golden, or the
+    # `--persona` file of the simulate CLI). Fails LOUD on a malformed persona —
+    # a silently relaxed max_turns or a missing knows would produce a simulation
+    # that tests nothing.
+    module PersonaLoader
+      class InvalidPersona < StandardError; end
+
+      module_function
+
+      def build(raw, source: "(inline)")
+        raise InvalidPersona, "#{source}: persona must be a mapping" unless raw.is_a?(Hash)
+
+        goal = presence(raw["goal"])
+        raise InvalidPersona, "#{source}: persona needs a non-empty 'goal'" if goal.nil?
+
+        knows = raw["knows"]
+        unless knows.is_a?(Hash) && !knows.empty?
+          raise InvalidPersona, "#{source}: persona needs a non-empty 'knows' mapping (the only facts it may assert)"
+        end
+
+        opens = presence(raw["opens_with"])
+        raise InvalidPersona, "#{source}: persona needs a non-empty 'opens_with'" if opens.nil?
+
+        max = raw["max_turns"]
+        unless max.is_a?(Integer) && max.positive?
+          raise InvalidPersona, "#{source}: persona needs 'max_turns' as a positive integer"
+        end
+
+        Persona.new(
+          goal: goal, style: presence(raw["style"]),
+          opens_with: opens,
+          knows: knows.transform_keys(&:to_s).transform_values(&:to_s),
+          max_turns: max
+        )
+      end
+
+      def presence(v)
+        s = v.to_s.strip
+        s.empty? ? nil : s
+      end
+    end
+  end
+end

data/lib/insika/evals/runner.rb

@@ -50,6 +50,15 @@ module Insika
       end
 
       def run_case(golden)
+        # A persona case is GENERATED, not replayed: the turns do not exist until a
+        # Simulator drives the conversation. The replay Runner cannot run it, and a
+        # silent no-op would read as a pass — so it is SKIPPED with the reason, and
+        # the Simulator (the simulate CLI) is the only driver.
+        if golden.simulated?
+          return RunCase.new(result: Assertions.skip(golden, "simulated case (persona) — drive it with `insika evals:simulate`"),
+                             timings: [])
+        end
+
         skip = skip_reason(golden)
         return RunCase.new(result: Assertions.skip(golden, skip), timings: []) if skip