insika 0.9.0 → 1.0.1

data/docs/TOOLS.md

@@ -20,8 +20,8 @@ kinds, and the distinction that matters is **who can change one at runtime**:
 **MCP tools are not data tools.** Configuring an enabled MCP **instance** (any
 surface below) is enough — its tools appear automatically, tagged
 `mcp:<instance>`, and each CALL goes straight to the server through a live,
-held client (stdio process / Streamable HTTP / SSE, with the full protocol
-handshake) — never a frozen snapshot. See [MCP servers](#mcp-servers) below.
+held native RubyLLM client (stdio / Streamable HTTP, with discovery and legacy
+handshake fallback) — never a frozen snapshot. See [MCP servers](#mcp-servers) below.
 
 Code tools **win name collisions** — you cannot register a data tool whose name
 shadows a code tool.
@@ -55,6 +55,9 @@ write path (`POST /v1/tools/manifest`) — writing this same shape via the DSL
 or Studio needs the literal header value instead; see
 "[The one gotcha](#the-one-gotcha-envsecret-templating-is-manifest-only)" below.
 
+`{{ctx.chat_id}}` is the external session ID. In multi-tenant mode, it excludes
+the authenticated tenant prefix used by Insika to isolate stored sessions.
+
 ### Parameters: the schema is the contract
 
 `parameters` is **JSON Schema**, and it reaches the provider verbatim — it is the only
@@ -281,6 +284,41 @@ backend rules such as quantity limits remain the backend's responsibility.
 The per-tool timeout starts after both gates are acquired. Trace duration includes
 queueing time, so it measures how long the model waited, not just backend execution.
 
+### Customer confirmation: a write the conversation approves
+
+Some writes should not happen on the strength of one ambiguous line — closing an
+order, deleting a record, sending a message on someone's behalf. Name them on the
+agent and the engine holds the call for the customer's word:
+
+```ruby
+customer_confirm "create_order"          # DSL; the Studio field is "customer confirm"
+```
+
+When the model calls a held tool, nothing runs. The engine records a pending action
+for the session and returns a `pending_confirmation` result carrying the arguments
+and an instruction: tell the customer exactly what will happen and ask. The turn ends
+with that question. On the next message the open hold is rendered at the tail of the
+context, and two system tools are available: `confirm_pending` runs the original call
+with the arguments recorded at the hold (no path exists to confirm different ones),
+`cancel_pending` drops it. A hold that the next message neither confirms nor cancels
+expires on its own — a customer who changed the subject did not agree.
+
+Three controls now sit on a write, and they compose in this order:
+
+| Control | Who decides | What happens to the turn | Declared on |
+| --- | --- | --- | --- |
+| Provenance (`requires_evidence`) | the ledger | the call is refused, the model is told how to resolve the id | the tool |
+| Customer confirmation (`customer_confirm`) | the customer, next message | the turn ends with a question | the agent |
+| Operator approval (`approvals_required`) | a person in the Studio | the turn suspends and waits | the agent |
+
+A tool is confirmed by the customer or approved by the operator, never both. The
+confirmed run still passes provenance, fencing, the side-effect record and the trace;
+the trace shows the hold as `gate: confirmation`, and the `:tool_result` event and the
+Responses stream report it as `status: held`, which the evals treat as neither a
+success nor an error. Whether the customer's "sim" means yes is the model's reading;
+what the engine guarantees is that the write runs only after an explicit question, a
+customer turn, and an explicit tool call.
+
 ### Grounding: policing claims against the ledger
 
 With the ledger fed, the pack declares how claims are policed — data on the agent,
@@ -367,7 +405,7 @@ such as suggestion chips (same mechanism, when a channel asks for it).
 A tool appears in the Studio panel and enters an agent's tool-loop when it is
 **registered** in the catalog **and** allowed by the agent's policy allowlist.
 Three ways to write a data tool into the store — all **hot** (registry and catalog
-reload, no restart):
+reload, no restart; with several workers, the others pick the change up within ~2 s):
 
 1. **DSL** — `data_tool(name:, …)` in a `Insika.agent { … }` block.
 2. **Studio** — the Tools panel editor.
@@ -390,6 +428,21 @@ any other way must ship literal values** — a real URL, and a real (masked on
 read) header value. `{{ctx.*}}` and `{{param}}` work everywhere (they resolve
 at turn time, not ingestion).
 
+The Studio **Tools** screen groups permissions by origin: native tools, HTTP
+tools, and MCP tools by server instance. Selection remains per tool; grouping
+does not change tool names or grant permissions.
+Each section can be collapsed. Filtering by tool or server name opens matching
+sections without changing selections; clearing the filter restores their state.
+Section selection buttons affect every tool in that section, including filtered
+tools, but never override denied tools. Save tools applies the changes.
+
+An MCP instance is a connection, not a single tool. Enable its individual tools
+for the agent in Studio. **Test connection** validates discovery with that
+instance's credentials; it does not validate a separate HTTP data tool or every
+remote tool's execution permissions. When replacing an HTTP tool with MCP,
+remove the old tool from the agent's permissions and update prompt references
+to the actual MCP tool names. Keep the egress allowlist restricted to required hosts.
+
 ## MCP servers
 
 An MCP **instance** is durable config — transport, target, credentials, an
@@ -399,19 +452,43 @@ instance is enabled, its tools appear in the catalog automatically (group
 server through a live, held client — the runtime never converts an MCP tool
 into a stored data tool.
 
-**Three transports**, picked by `transport:`:
+Each tool is named after its instance: `<instance>__<tool>`, with the instance
+lowercased and anything outside `a-z0-9` turned into `_` (instance
+`shop-staging`, tool `list_products` → `shop_staging__list_products`). That is
+the name the model calls and the one an agent's allowlist holds, so two
+instances that offer the same tool (a store's production and staging) stay two
+tools, each reaching its own server. Per-tool overrides (`tools:`) still use the
+server's own tool name. A qualified name over 64 characters is skipped with a
+warning, since providers reject it: shorten the instance name.
+
+The deployment's legacy `import_mcp_tools` command now aliases
+`refresh_mcp_tools`: it returns `{ instance:, tools: }` and emits
+`mcp_tools_refreshed`, replacing the old created/updated import report.
+Previously imported data tools remain unchanged and take precedence over live
+tools with the same name. After refreshing and verifying the live instance,
+delete those snapshots through the normal data-tool controls to use live calls.
+`insika doctor` identifies them by their `mcp:<instance>` group.
+
+**Two supported transports**, picked by `transport:`:
 
 | Transport | Target | Notes |
 |---|---|---|
 | `stdio` | `command` + `args`, run as a child process, `env` is its process environment | requires `INSIKA_MCP_STDIO=1` — see below |
-| `http` | `url` + `headers` (Streamable HTTP, the modern default) | egress-guarded like any outbound URL |
-| `sse` | `url` + `headers` | same egress guard as `http` |
+| `http` | `url` + `headers` (Streamable HTTP) | egress-guarded; HTTPS required outside loopback |
+
+Legacy `sse` records remain stored, but cannot connect through the native client.
+Change the record to `http` with the server's Streamable HTTP endpoint. Event-stream
+responses over Streamable HTTP remain supported; only the old SSE transport is removed.
 
 **The stdio gate.** A stdio instance is arbitrary command execution by
 config — it saves, but refuses to start ("stdio disabled by env") until the
 operator sets `INSIKA_MCP_STDIO=1` (config-over-convention, the same pattern
-as the egress envs). `http`/`sse` need no such gate; their URL is checked by
-the normal egress allowlist instead.
+as the egress envs). `http` needs no such gate; its URL goes through the
+egress guard instead: HTTPS, and a host that resolves to a private address
+needs `INSIKA_EGRESS_ALLOW_PRIVATE` and a place in `INSIKA_EGRESS_HOSTS`. A
+public host is not pinned by that list, since the operator fixed the URL and
+the model cannot change it. Native MCP additionally refuses plain HTTP
+outside loopback, even when `INSIKA_EGRESS_ALLOW_HTTP` is enabled.
 
 **Credentials are never visible in plaintext.** `env` (stdio) and `headers`
 (http/sse) mask every value as `__OCULTO__` on read, everywhere (CLI, API,
@@ -443,6 +520,31 @@ held client, which does its own discovery on first use regardless of whether
    `enabled` flag and its credentials are the **operator's** — a Studio/CLI/API
    edit made after boot is never clobbered back by the next restart.
 
+   The **first** boot after a declaration also lists the server's tools, because
+   until they are listed the agent is offered none of them and answers out of its
+   own head instead. A server that cannot be listed (stdio behind a closed gate, a
+   host that is down) does not stop the boot — it is warned about by name, and the
+   agent runs without those tools until `insika mcp refresh <name>` succeeds.
+
+   **What the deployment trusts each tool with** — a server describes what its tools
+   *do*; only the deployment can say which of its answers are evidence and which
+   parameter may only ever carry an id something already returned:
+
+   ```ruby
+   mcp "store", transport: :http, url: ENV.fetch("STORE_MCP"),
+       tools: {
+         # the store's own field names: no server renames them for us
+         "search_products" => { evidence: { kind: "products", items: "products",
+                                            id: "product_id", line: "line" } },
+         # a write that may only take an id the customer was actually shown
+         "add_to_cart" => { requires_evidence: ["product_id"] }
+       }
+   ```
+
+   Both are refused at ingestion, never at the turn: an `evidence:` typo that
+   survived would extract nothing and the gate below it would block every write.
+   A tool nobody names here behaves exactly as it did before.
+
 2. **CLI** — `insika mcp list | add | remove | import <file.json> | test <name> |
    refresh <name>`. `add` takes `--name`, `--transport`, `--command`/`--arg`
    (repeatable) or `--url`/`--header "Name: value"` (repeatable)/`--env
@@ -464,7 +566,7 @@ held client, which does its own discovery on first use regardless of whether
 
    `insika mcp import FILE.json` upserts every entry (a bare `command` implies
    `stdio`; a bare `url` implies `http`; add `"transport": "sse"` explicitly
-   for SSE — the bare format has no other way to spell it). The same parser
+   only to retain a legacy SSE record pending migration). The same parser
    backs `PUT /v1/mcp` and Studio's "Import JSON" box; `export` produces the
    document back with secrets masked as `__OCULTO__`, so round-tripping an
    export never wipes a stored credential.

data/docs/operate.md

@@ -10,10 +10,13 @@ permalink: /operate/
 Running it once it is live: seeing what happened, firing turns nobody sent,
 handing back a report, and knowing what the box will take before it takes it.
 
+- **[Studio](STUDIO.md)** — the operator UI: live conversations, why each reply, the review inbox, what a change did.
 - **[Observability](OBSERVABILITY.md)** — the event stream, and turns as OpenTelemetry traces and metrics.
 - **[Schedules](SCHEDULING.md)** — recurring turns the engine fires on its own tick.
 - **[Artifacts](ARTIFACTS.md)** — a report the agent can hand you a URL to.
 - **[Load test](LOADTEST.md)** — end-to-end load testing, and comparing topologies before you choose one.
 - **[Soak](SOAK.md)** — the long run that finds what a short one cannot.
 - **[Benchmark](BENCHMARK.md)** — the engine's measured overhead, reproducible without an API key.
+- **[Cross-harness bench](CROSS-HARNESS-BENCH.md)** — the same store answered by six harnesses, graded on the store's own state.
+- **[Performance](PERFORMANCE.md)** — what keeps a turn cheap, and what was tried and left out.
 {: .card-grid }

data/lib/insika/agent_defaults.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Insika
+  # Platform defaults for agent fields (Settings["agent_defaults"]): an agent
+  # with no value of its own for an INHERITABLE field runs with the platform's.
+  # The agent's own value always wins, whole (no merge of the two).
+  #
+  # Applied only where turns read profiles (the graph, through ProfileSource
+  # below). Authoring (Studio, pack import) reads the agent's own record, so
+  # saving an agent never copies a default into it and it keeps inheriting.
+  #
+  # FIELDS are the ones where "absent" already means "not configured". Fields
+  # where absent means something else (tools_allow nil = every tool) or where
+  # absent and off read the same (the memory/fencing booleans) are left out.
+  module AgentDefaults
+    FIELDS = %w[reliability knowledge memory_retrieval budget alerts guardrails
+                grounding followup distill harvest].freeze
+
+    module_function
+
+    # -> the profile, rebuilt with the defaults it lacks (the same object when
+    # there is nothing to fill).
+    def apply(profile, defaults)
+      fill = FIELDS.each_with_object({}) do |field, acc|
+        value = defaults[field]
+        acc[field.to_sym] = value if !value.nil? && profile.public_send(field).nil?
+      end
+      return profile if fill.empty?
+
+      AgentProfile.build(**profile.to_h.merge(fill))
+    end
+
+    # Like #apply, but a default the agent cannot be built with (saved before it
+    # was validated, or a rerank model the registry dropped since) leaves the
+    # agent on its own values: one bad default must not stop every turn.
+    def apply_safely(profile, defaults)
+      apply(profile, defaults)
+    rescue Insika::ValidationError => e
+      warn "[insika] agent defaults not applied to #{profile.id}: #{e.message}"
+      profile
+    end
+
+    # Raises ValidationError unless an agent can be built with these defaults.
+    def validate!(defaults)
+      fields = defaults.to_h { |field, value| [field.to_sym, value] }
+      AgentProfile.build(id: "agent-defaults", model: nil, **fields)
+      defaults
+    end
+
+    # The source as turns read it (defaults + kits applied), for turn-time readers
+    # wired outside the graph (workflow triggers, persona evals). No settings store
+    # = nothing to apply, the source as is.
+    def for_turns(source, settings_store)
+      return source if settings_store.nil?
+
+      ProfileSource.new(Insika::ProfileSource.coerce(source), settings_store: settings_store)
+    end
+
+    # The agent's own records behind a profile source: what authoring reads and
+    # writes. A plain source is its own.
+    def own(source) = source.is_a?(ProfileSource) ? source.source : source
+
+    # A ProfileSource that hands out profiles with the platform defaults and the
+    # agent's kits (Insika::Kits) applied.
+    # Read-only: writing a profile read here would save the defaults into the
+    # agent, so put/delete refuse; writers use #source (AgentDefaults.own).
+    # Other reads (all_raw) go to the wrapped source untouched.
+    class ProfileSource
+      include Insika::ProfileSource
+
+      attr_reader :source
+
+      def initialize(source, settings_store:)
+        @source = source
+        @settings_store = settings_store
+      end
+
+      def fetch(id)
+        profile = @source.fetch(id)
+        profile && Insika::Kits.apply(fill(profile, normalized), kits)
+      end
+
+      def all
+        values = normalized
+        by_name = kits
+        @source.all.map { |profile| Insika::Kits.apply(fill(profile, values), by_name) }
+      end
+
+      def ids = @source.ids
+
+      def put(*) = raise(Insika::Error, "agent profiles are written through their own source (AgentDefaults.own)")
+      def delete(*) = put
+
+      def respond_to_missing?(name, include_private = false) = @source.respond_to?(name, include_private) || super
+
+      def method_missing(name, ...)
+        return super unless @source.respond_to?(name)
+
+        @source.public_send(name, ...)
+      end
+
+      private
+
+      # Settings["kits"] — applied after the defaults (Insika::Kits).
+      def kits = @settings_store.get["kits"] || {}
+
+      # Every inheritable field is normalized on its own by AgentProfile.build,
+      # so a profile takes the normalized values as they are (Data#with) and is
+      # not rebuilt per read.
+      def fill(profile, values)
+        missing = values.select { |field, _| profile.public_send(field).nil? }
+        missing.empty? ? profile : profile.with(**missing)
+      end
+
+      # The defaults as AgentProfile.build normalizes them, rebuilt only when the
+      # stored defaults change. Frozen: every profile shares them. A field that
+      # does not build is left out (warned once per change), so one bad default
+      # cannot stop every turn.
+      def normalized
+        raw = @settings_store.get["agent_defaults"] || {}
+        digest = raw.hash
+        return @normalized if digest == @normalized_digest
+
+        @normalized = build_values(raw.slice(*FIELDS).compact)
+        @normalized_digest = digest
+        @normalized
+      end
+
+      def build_values(raw)
+        raw.filter_map do |field, value|
+          built = AgentProfile.build(id: "agent-defaults", model: nil, field.to_sym => value)
+          [field.to_sym, Ractor.make_shareable(built.public_send(field))]
+        rescue Insika::ValidationError => e
+          warn "[insika] agent defaults: #{field} not applied: #{e.message}"
+          nil
+        end.to_h
+      end
+    end
+  end
+end

data/lib/insika/agent_file_store.rb

@@ -31,6 +31,13 @@ module Insika
       entry(agent_id, filename.to_s)&.fetch("content", nil)
     end
 
+    # -> { name => content } every file of the agent, from ONE read of its record
+    # (which also carries the version history). Callers that need several files
+    # use this instead of `read` per file.
+    def contents(agent_id)
+      files(agent_id).transform_values { |entry| entry["content"] }
+    end
+
     # -> [String] the agent's file names, lexicographic order.
     def list(agent_id)
       files(agent_id).keys.sort
@@ -88,6 +95,11 @@ module Insika
       entry(agent_id, filename.to_s)&.fetch("history", []) || []
     end
 
+    # -> String | nil: when the current content was written (iso8601).
+    def updated_at(agent_id, filename)
+      entry(agent_id, filename.to_s)&.fetch("updated_at", nil)
+    end
+
     # Restores version `index` from history as the current content (a new write:
     # the current one goes to the top of history). -> Hash (entry) | raises if index
     # invalid / file nonexistent.

data/lib/insika/agent_profile.rb

@@ -35,12 +35,17 @@ module Insika
     #                                   a per-skill flag forced one decision onto every
     #                                   allowlist holding the skill. NOT `Allowlist`
     #                                   semantics — nil means NONE here (SkillCatalog#eager_for).
+    :kits,                            # kit names (Insika::Kits): bundles of skills/tools applied
+    #                                   at READ time by AgentDefaults::ProfileSource — never
+    #                                   copied into the record. Always a [String] ([] = none).
     :context_providers,               # provider allowlist
     :workflows_allow,                 # applied by WorkflowAllowlist
     :policies,                        # names in the Policy Registry
     :prompt_refs,                     # names in the Prompt Catalog
     :limits,                          # timeouts/budgets
     :approvals_required,              # tools that require approval (ApprovalRequired)
+    :customer_confirm,                # tools the CUSTOMER confirms on the next message: the
+    #                                   call is held, the turn ends with a question (nil = none)
     :capabilities,                    # intents the agent can trigger.
     #                                   nil = NONE (opt-in, see above).
     :subagents,                       # allowlist of child agent ids this agent MAY spawn
@@ -51,9 +56,11 @@ module Insika
     :tools_deferred,                  # searchable-not-wired tools (Tool Search).
     #                                   nil = no deferred (all eager — parity);
     #                                   [names] ⊆ allowed_tools, exposed via tool_search.
+    :shared_conversations,            # opt-in authoritative conversation persistence
     :memory,                          # cross-session memory.
     #                                   nil/false = OFF (parity: provider []; the `remember`
     #                                   tool not wired); true = ON. Same opt-in as capabilities.
+    :memory_retrieval,                # optional reranked context selection; nil = legacy memory block.
     :prompt_caching,                  # Anthropic prompt caching (R3): nil/false = OFF
     #                                   (parity); true = ON. Same opt-in as `memory`. When ON
     #                                   AND the resolved provider is Anthropic, ChatBuilder sets
@@ -95,7 +102,10 @@ module Insika
     #                                   release: the goldens were baselined on unfenced bytes.
     :params,                          # LLM generation params: a Hash with
     #                                   temperature/max_tokens/thinking, applied to the chat at
-    #                                   stage 5. {} = provider defaults (parity).
+    #                                   stage 5. {} = provider defaults (parity). Plus
+    #                                   `provider_routing` — which UPSTREAM serves the model, for
+    #                                   a gateway that has several; emitted under the wire key
+    #                                   `provider` (OpenRouter's shape).
     :budget,                          # spend caps per (tenant, agent) over
     #                                   CALENDAR windows (WS2): { "daily" => int,
     #                                   "monthly" => int, "soft" => bool, "alert_at" => 0.8 }.
@@ -330,9 +340,10 @@ module Insika
     # platform `default_model` (Settings) at turn start via the ModelResolver.
     def self.build(id:, model: nil, provider: nil, base_prompt: "", prompt_files: [],
                    tools_allow: nil, tools_deny: [], tools_allow_groups: nil, skills: nil,
-                   skills_eager: nil, context_providers: nil, workflows_allow: nil,
+                   skills_eager: nil, kits: nil, context_providers: nil, workflows_allow: nil,
                    policies: [], prompt_refs: [], limits: {}, approvals_required: nil,
-                   capabilities: nil, subagents: nil, tools_deferred: nil, memory: nil,
+                   customer_confirm: nil,
+                   capabilities: nil, subagents: nil, tools_deferred: nil, memory: nil, memory_retrieval: nil, shared_conversations: false,
                    prompt_caching: nil, tool_persistence: nil, tool_output_compression: nil,
                    fencing: nil, params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
                     refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {},
@@ -344,16 +355,19 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
         prompt_files: Array(prompt_files), tools_allow: tools_allow,
         tools_deny: Array(tools_deny), tools_allow_groups: tools_allow_groups, skills: skills,
         skills_eager: skills_eager,
+        kits: Array(kits).map(&:to_s).uniq,
         context_providers: context_providers, workflows_allow: workflows_allow,
         policies: normalize_policies(policies, tools_allow: tools_allow, tools_deny: tools_deny,
                                      tools_allow_groups: tools_allow_groups),
         prompt_refs: Array(prompt_refs),
         limits: DEFAULT_LIMITS.merge(limits), approvals_required: approvals_required,
+        customer_confirm: normalize_customer_confirm(customer_confirm, approvals_required),
         capabilities: capabilities,
         # opt-in like capabilities: nil => NONE. Array-normalize a present value so
         # readers get a clean [] and the ChatBuilder gate (present? => wire) is stable.
         subagents: subagents.nil? ? nil : Array(subagents).map(&:to_s),
-        tools_deferred: tools_deferred, memory: memory,
+        tools_deferred: tools_deferred, memory: memory, shared_conversations: shared_conversations == true,
+        memory_retrieval: normalize_memory_retrieval(memory_retrieval),
         prompt_caching: prompt_caching, tool_persistence: tool_persistence,
         tool_output_compression: tool_output_compression, fencing: fencing,
         # The free-form hashes arrive with symbol keys (internal build) OR string
@@ -402,10 +416,9 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
         # free-form hashes; shape-validated by the command/engine/doctor
         # (never here — the refinement precedent). nil = off (parity).
         harvest: Coercion.deep_stringify(harvest),
-        # knowledge is profile DATA, deep-stringified like the other
-        # free-form hashes; shape-validated by the extractor/doctor
-        # (never here — the refinement precedent). nil = off (parity).
-        knowledge: Coercion.deep_stringify(knowledge),
+        # knowledge is profile DATA. Legacy extraction remains free-form;
+        # an explicit rerank declaration is validated when loaded.
+        knowledge: normalize_knowledge(knowledge),
         # schedules is profile DATA, deep-stringified like the other
         # free-form hashes (an ARRAY of declarations); parsed into
         # Insika::Schedule entries by the engine/doctor/Studio (shape-validated
@@ -414,6 +427,46 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
       )
     end
 
+    def self.normalize_knowledge(value)
+      config = Coercion.deep_stringify(value)
+      return config unless config.is_a?(Hash) && config.key?("rerank")
+
+      validate_rerank(config, "knowledge")
+      config
+    end
+
+    def self.normalize_memory_retrieval(value)
+      return nil if value.nil?
+
+      config = Coercion.deep_stringify(value)
+      raise ValidationError, "memory_retrieval must be an object" unless config.is_a?(Hash)
+
+      validate_rerank(config, "memory_retrieval", require_top_k: true)
+      config
+    end
+
+    def self.validate_rerank(config, field, require_top_k: false)
+      rerank = config["rerank"]
+      raise ValidationError, "#{field}.rerank must be an object" unless rerank.is_a?(Hash)
+
+      top_k = require_top_k ? config["top_k"] : config.fetch("top_k", 5)
+      limit = rerank["candidate_limit"]
+      timeout = rerank["timeout_seconds"]
+      valid = top_k.is_a?(Integer) && top_k.positive? &&
+              limit.is_a?(Integer) && limit >= top_k && limit <= 100 &&
+              timeout.is_a?(Numeric) && timeout.finite? && timeout.positive? &&
+              %w[provider model].all? { |key| rerank[key].is_a?(String) && !rerank[key].strip.empty? }
+      raise ValidationError, "invalid #{field}.rerank configuration" unless valid
+
+      require "ruby_llm"
+      begin
+        model = RubyLLM.models.find(rerank["model"], provider: rerank["provider"])
+      rescue RubyLLM::ModelNotFoundError
+        raise ValidationError, "#{field}.rerank model is not registered for provider"
+      end
+      raise ValidationError, "#{field}.rerank model does not support reranking" unless model.type == :rerank
+    end
+
     # Declaring a tool allow/deny list IS opting into it. The list is only ever
     # applied by the builtin `tool_allowlist` policy, and the Policy::Engine runs
     # ONLY the policies a profile names — so a profile with `tools_allow: [a, b]`
@@ -461,6 +514,23 @@ outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil
       names
     end
 
+    # nil/empty -> nil (off); else [String], trimmed, uniq. A tool is confirmed by
+    # the customer OR approved by the operator, never both: the two hold a call in
+    # opposite ways (the turn ends with a question vs. the turn suspends), and one
+    # tool cannot do both at once.
+    def self.normalize_customer_confirm(list, approvals)
+      names = Array(list).map { |n| n.to_s.strip }.reject(&:empty?).uniq
+      return nil if names.empty?
+
+      both = names & Array(approvals).map(&:to_s)
+      unless both.empty?
+        raise Insika::ValidationError,
+              "customer_confirm and approvals_required overlap (#{both.join(', ')}): a tool is " \
+              "confirmed by the customer or approved by the operator, not both"
+      end
+      names
+    end
+
     # opt-in for an optional tool = being in the agent's allow list.
     def tool_opted_in?(name)
       Array(tools_allow).include?(name)

data/lib/insika/artifact_signing.rb

@@ -22,6 +22,17 @@ module Insika
     AUTHENTICATED_PATH = "/studio/artifacts/%{id}/content"
     SIGNED_PATH = "/studio/artifacts/s/%{id}?exp=%{exp}&sig=%{sig}"
 
+    # The Studio's signing config, read from the environment.
+    # -> { key:, ttl:, base_url: } | nil (no signing key -> no signed surface).
+    def studio_config
+      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
+
     # -> hex token (64 chars) | nil when the key is blank (no signed surface).
     def sign(id:, expires_at:, key:)
       key = key.to_s