insika 0.8.0 → 1.0.1

data/lib/insika/pack_importer.rb

@@ -17,6 +17,10 @@ module Insika
   # tools rewritten; the allowlists (prompt_files/skills/tools_allow) are
   # AUTHORITATIVE from the pack, so whatever left the pack leaves the agent
   # (isolation and no drift). An in-flight turn keeps the profile it captured.
+  #
+  # `limits` and `params` are the exception, and the only one: they MERGE per key
+  # (see KNOB_BAGS). A client that publishes two limits is not saying the agent has
+  # only two.
   class PackImporter
     def initialize(bus:, profiles:)
       @bus = bus
@@ -30,13 +34,14 @@ module Insika
       id = presence(pack.config[:id]) ||
            (raise Insika::ValidationError, "pack missing config.id")
 
-      created = @profiles[id].nil?
+      existing = @profiles[id]
+      created = existing.nil?
       # create_agent rejects an already-existing id; update_agent requires it to
       # exist — the choice by presence makes the import an upsert.
-      dispatch(created ? :create_agent : :update_agent, agent_attrs(pack, id))
+      dispatch(created ? :create_agent : :update_agent, agent_attrs(pack, id, existing))
 
       pack.files.each { |name, body| dispatch(:write_agent_file, { agent_id: id, file: name, content: body }) }
-      pack.skills.each { |name, body| dispatch(:write_skill, { name: name, content: body }) }
+      pack.skills.each { |name, body| dispatch(:write_skill, { name: name, content: body, agent: id }) }
       pack.tools.each { |defn| dispatch(:write_data_tool, defn) }
 
       { agent_id: id, created: created,
@@ -44,8 +49,8 @@ module Insika
     end
 
     # Removes the agent (delete_agent). Does NOT delete skills/tools/files: they
-    # may be shared and the SkillStore/ToolStore are global — selective removal is
-    # operator work. NotFoundError (missing agent) propagates -> 404.
+    # may be needed again on re-import; tools may also be shared. Selective removal
+    # is operator work. NotFoundError (missing agent) propagates -> 404.
     def delete(id)
       dispatch(:delete_agent, { id: id })
       { agent_id: id, deleted: true }
@@ -58,8 +63,10 @@ module Insika
     # its OWN pack (per-store isolation) and re-provisioning removes what left.
     #   - prompt_files = the pack's .md files (write_agent_file also registers;
     #     union is a no-op). Setting here makes the list authoritative (removes the ones that left).
-    #   - skills = the pack's skills/ dirs (explicit allowlist; [] when the pack
-    #     has none — never nil=all, which would leak skills from other stores).
+    #   - skills = the pack's skills/ dirs ∪ config.skills (names of SHARED skills the
+    #     pack references without copying — one body serves every agent that lists
+    #     it). [] when both are empty — never nil=all, which would leak skills from
+    #     other stores.
     #   - tools_allow = (config.tools_allow) ∪ (the pack's tool names) — guarantees
     #     the agent can call its own data-tools. [] when neither exists —
     #     never nil=all: the ToolStore is GLOBAL, so a tool-less pack would
@@ -70,11 +77,12 @@ module Insika
     #     the tools of the enabled groups (union with tools_allow) go to the model;
     #     those of disabled groups are cut BEFORE the turn (resolves the OpenClaw
     #     tool-call waste, where the flag only exists in Rails).
-    def agent_attrs(pack, id)
+    def agent_attrs(pack, id, existing = nil)
       attrs = pack.config.dup
       attrs[:id] = id
+      merge_knob_bags!(attrs, existing)
       attrs[:prompt_files] = pack.files.keys unless pack.files.empty?
-      attrs[:skills] = pack.skills.keys
+      attrs[:skills] = pack.skills.keys | Array(pack.config[:skills]).map(&:to_s)
 
       pack_tools = pack.tools.map { |t| tool_name(t) }
       allow = Array(pack.config[:tools_allow]).map(&:to_s) | pack_tools
@@ -85,6 +93,43 @@ module Insika
       attrs
     end
 
+    # The bags a re-import must not ERASE. `limits` and `params` are flat
+    # `key => scalar` maps whose keys are independent of one another: a provisioning
+    # client that sends two of them is saying something about those two and nothing
+    # about the rest. `update_agent` replaces a sent field wholesale (correct for the
+    # Studio, which always posts the complete bag), so without this a client that
+    # publishes `limits: {turn_timeout:, context_budget:}` silently drops every knob
+    # an operator set here — `queue_mode`, `debounce_ms`, `chat_rate_limit` — on the
+    # next publish of an unrelated playbook.
+    #
+    # NOT the authoritative list (`prompt_files`/`skills`/`tools_allow`), which the
+    # pack is supposed to erase: those are isolation boundaries and a name that left
+    # the pack must leave the agent. A knob is not a boundary.
+    #
+    # The pack still WINS per key. What it cannot do is remove a key by omission —
+    # removing a knob is Studio (or operator) work, which is where it was set.
+    KNOB_BAGS = %i[limits params].freeze
+
+    # Keys are symbolized on BOTH sides before merging: the profile holds symbols and
+    # the pack's nested hashes arrive with whatever the JSON had, so a raw merge would
+    # leave `:turn_timeout` and `"turn_timeout"` side by side and let the later
+    # normalization pick by insertion order.
+    def merge_knob_bags!(attrs, existing)
+      return if existing.nil?
+
+      KNOB_BAGS.each do |bag|
+        patch = attrs[bag]
+        next unless patch.is_a?(Hash)
+
+        current = existing.respond_to?(bag) ? existing.public_send(bag) : nil
+        next unless current.is_a?(Hash)
+
+        attrs[bag] = sym_keys(current).merge(sym_keys(patch))
+      end
+    end
+
+    def sym_keys(hash) = hash.each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+
     # PER-FLAG CUT (/, STATIC pilot): derives the agent's
     # per-group allowlist from FLAGS declared in the pack config — DATA, never a
     # core convention. The engine doesn't know "groceries_v2"/"b2b": the pack

data/lib/insika/packaging.rb

@@ -55,7 +55,10 @@ module Insika
 
     # The never-ship set: the studio JS toolchain (only assets/dist ships) and
     # the docs' own Jekyll Gemfile/config.
-    NEVER_SHIP_PREFIXES = ["node_modules", "lib/insika/studio/test/", "lib/insika/studio/assets/src/"].freeze
+    # docs/superpowers/ holds internal plans (customer names, live results): never
+    # tracked here any more, and never shipped even if one is committed by mistake.
+    NEVER_SHIP_PREFIXES = ["node_modules", "lib/insika/studio/test/", "lib/insika/studio/assets/src/",
+                           "docs/superpowers/"].freeze
     NEVER_SHIP_PATHS = %w[
       docs/Gemfile docs/Gemfile.lock docs/_config.yml
       lib/insika/studio/README.md lib/insika/studio/package.json
@@ -97,14 +100,20 @@ module Insika
     # bracket classes collapsed), so the corpus data's `voc[êe]`-style
     # patterns are caught by the same table.
     def domain_content?(path)
-      text = path.to_s.end_with?(".rb") ? ruby_text(path) : File.read(path)
-      fold(text).match?(PT_BR_TOKENS)
+      fold(payload_text(path)).match?(PT_BR_TOKENS)
     end
 
     # -> bool: does a payload file mention the demo persona name (`bia`)?
     def persona_content?(path)
-      text = path.to_s.end_with?(".rb") ? ruby_text(path) : File.read(path)
-      text.match?(PERSONA_NAME)
+      payload_text(path).match?(PERSONA_NAME)
+    end
+
+    # -> String: the text the audit scans. Ruby goes through `ruby_text`;
+    # everything else is read as-is with invalid UTF-8 DROPPED — the payload
+    # also carries binary assets (the Studio's embedded webfonts), which hold
+    # no readable content but would otherwise raise on the first match.
+    def payload_text(path)
+      path.to_s.end_with?(".rb") ? ruby_text(path) : File.read(path).scrub("")
     end
 
     # The Ruby source as the audit reads it: heredoc bodies verbatim, string +

data/lib/insika/pending_action_store.rb

@@ -20,18 +20,30 @@ module Insika
 
     STATUSES = %i[pending approved rejected].freeze
 
-    PendingAction = Data.define(:id, :task_id, :turn, :tool, :args,
+    # Who resolves the action: the OPERATOR in the Studio (the turn suspended and
+    # waits) or the CUSTOMER on the next message (the turn ended with a question).
+    # Absent on a stored row = operator, so rows written before `kind` keep meaning.
+    OPERATOR = "operator"
+    CUSTOMER = "customer"
+
+    PendingAction = Data.define(:id, :task_id, :session_id, :turn, :tool, :args, :kind,
                                 :status, :requested_at, :resolved_by, :resolved_at)
 
+    # One row per (session, tool) for a customer hold: a crash-and-re-execute of the
+    # holding turn rewrites the same row instead of leaving two open.
+    def self.confirmation_id(session_id, tool) = "confirm:#{session_id}:#{tool}"
+
     def initialize(store:)
       @store = store
     end
 
     # -> PendingAction (:pending). `args` is the Hash of the tool call's arguments.
-    def create(task_id:, turn:, tool:, args: {}, id: SecureRandom.uuid)
+    def create(task_id:, turn:, tool:, args: {}, id: SecureRandom.uuid, kind: OPERATOR, session_id: nil)
       record = {
         "id" => id.to_s,
         "task_id" => task_id.to_s,
+        "session_id" => session_id&.to_s,
+        "kind" => kind.to_s,
         "turn" => turn,
         "tool" => tool.to_s,
         "args" => deep_stringify(args),
@@ -52,29 +64,31 @@ module Insika
 
     # -> [PendingAction] :pending for the task (recovery/UI). O(n) scan — single-node,
     # like TaskStore#running_or_interrupted.
-    def open_for(task_id)
+    def open_for(task_id, kind: nil)
       id = task_id.to_s
-      @store.list(SCOPE, KEY_PREFIX).filter_map do |key|
-        record = @store.get(SCOPE, key)
-        next if record.nil?
+      scan_open(kind).select { |pa| pa.task_id == id }
+    end
 
-        pa = to_pending(record)
-        pa if pa.status == :pending && pa.task_id == id
-      end
+    # -> [PendingAction] :pending for the session — the customer's holds live here,
+    # keyed by the conversation rather than the task that held them.
+    def open_for_session(session_id, kind: nil)
+      id = session_id.to_s
+      scan_open(kind).select { |pa| pa.session_id == id }
+    end
+
+    # Customer holds of a session that an EARLIER task created and nothing
+    # resolved: the next message did not agree, so the engine rejects them.
+    # -> [PendingAction] the ones it expired.
+    def expire_customer_holds(session_id:, except_task_id:)
+      keep = except_task_id.to_s
+      open_for_session(session_id, kind: CUSTOMER).reject { |pa| pa.task_id == keep }
+                                                 .map { |pa| resolve(pa.id, decision: :rejected, operator: "engine:expired") }
     end
 
     # -> [PendingAction] every :pending across all tasks — the approvals inbox
     # (Studio). Single O(n) scan (vs. open_for per task = O(n·m)); the
     # UI resolves task context afterwards via TaskStore#find.
-    def all_open
-      @store.list(SCOPE, KEY_PREFIX).filter_map do |key|
-        record = @store.get(SCOPE, key)
-        next if record.nil?
-
-        pa = to_pending(record)
-        pa if pa.status == :pending
-      end
-    end
+    def all_open(kind: nil) = scan_open(kind)
 
     # -> resolved PendingAction. Only resolves :pending: a double resolution
     # or an invalid decision -> ValidationError; absent -> NotFoundError.
@@ -101,13 +115,26 @@ module Insika
 
     def key_for(id) = "#{KEY_PREFIX}#{id}"
 
+    def scan_open(kind)
+      wanted = kind&.to_s
+      @store.list(SCOPE, KEY_PREFIX).filter_map do |key|
+        record = @store.get(SCOPE, key)
+        next if record.nil?
+
+        pa = to_pending(record)
+        pa if pa.status == :pending && (wanted.nil? || pa.kind == wanted)
+      end
+    end
+
     def to_pending(record)
       PendingAction.new(
         id: record["id"],
         task_id: record["task_id"],
+        session_id: record["session_id"],
         turn: record["turn"],
         tool: record["tool"],
         args: record["args"],
+        kind: record["kind"] || OPERATOR,
         status: record["status"].to_sym,
         requested_at: record["requested_at"],
         resolved_by: record["resolved_by"],

data/lib/insika/plugin/loader.rb

@@ -78,8 +78,9 @@ module Insika
         @announced_roots.any? { |root| dir == root || dir.start_with?("#{root}#{File::SEPARATOR}") }
       end
 
-      # One manifest per directory: insika.plugin.yml takes precedence over
+      # One manifest per directory: insika.plugin.yml takes precedence over a leftover
       # plugin.yml (same dir). Order preserved (root precedence — first wins via `seen`).
+      # plugin.yml is still globbed only so load_manifest can refuse it out loud.
       def manifest_files
         selected = {}
         @roots.each do |root|
@@ -96,7 +97,8 @@ module Insika
         return nil unless manifest.is_a?(Hash)
 
         if File.basename(file) == "plugin.yml"
-          warn "[plugin #{manifest['id']}] plugin.yml is deprecated — rename to insika.plugin.yml"
+          warn "[plugin #{manifest['id']}] plugin.yml was removed in 1.0 and is not loaded — rename to insika.plugin.yml"
+          return nil
         end
         manifest
       rescue StandardError => e

data/lib/insika/prefix_fingerprint.rb

@@ -9,47 +9,52 @@ module Insika
   # (name + description + parameters.inspect, executor.rb:957). Outputs are
   # PII-free digests: it never sees message text, only hashes leave this class.
   # Pure stdlib (digest/sha2), no gem, no IO.
+  #
+  # The chain follows the cache boundary: the cumulative "prefix" is over the
+  # IDENTITY categories + tool_schemas only — the bytes the cache breakpoint
+  # actually covers. Volatile categories (memory, knowledge, briefing, request)
+  # render below the breakpoint, so a change there is not a prefix invalidation;
+  # they still get their own digest (the trace shows them) but sit AFTER the
+  # "prefix" key, outside the chain.
   class PrefixFingerprint
     # -> { "prompt" => "sha256…", …, "tool_schemas" => "sha256…",
-    #      "prefix" => "sha256…" }
-    # Keys are the demodulized, downcased provider ids, in render order.
+    #      "prefix" => "sha256…", "memory" => "sha256…", … }
+    # Keys are the demodulized, downcased provider ids. Order: identity
+    # categories (render order), "tool_schemas", "prefix", then the volatile
+    # categories — everything before "prefix" is the chain.
     # A category with no fragments is absent (not an empty hash).
     # The category digest = SHA256 of the category's fragments joined "\n\n"
     # (the Builder's separator — the digest matches rendered bytes).
-    # "prefix" = SHA256 of the category digests concatenated IN CHAIN ORDER
-    # (identity categories, then volatile, then tool_schemas) — any divergence
-    # anywhere above the boundary changes it.
+    # "prefix" = SHA256 of the chain digests concatenated in order — any
+    # divergence anywhere above the boundary changes it. A fragment with no
+    # layer stamp reads as volatile, like everywhere else.
     def self.compute(system_fragments, tool_serial:)
-      digests = {} # category name -> digest, insertion = render order
-      grouped = system_fragments.group_by { |f| category(f.source) }
-      grouped.each do |name, frags|
-        digests[name] = digest(frags.map(&:content).join("\n\n"))
-      end
+      identity, volatile = system_fragments.partition { |f| (f.layer || :volatile) == :identity }
+      digests = category_digests(identity)
       digests["tool_schemas"] = digest(tool_serial.to_s) unless tool_serial.nil?
       digests["prefix"] = digest(digests.values.join) unless digests.empty?
-      digests
+      digests.merge(category_digests(volatile))
     end
 
-    # -> String | nil. The first category (in CURRENT chain order) whose digest
-    # differs or is absent from `previous`; else the first PREVIOUS key now
-    # absent from the current chain (a vanished block is a divergence too);
-    # else nil. nil `previous` (first turn) -> nil. The returned name is a
-    # category id — PII-free by construction.
-    #
-    # The cumulative "prefix" key is deliberately SKIPPED in the scan: its
-    # digest changes whenever ANY category moves, so scanning it would shadow a
-    # vanished block (every surviving category matches, "prefix" differs, and
-    # the vanished-fallback below becomes unreachable — reporting `broke:
-    # prefix` instead of the category that actually left).
+    # -> String | nil. nil when the cumulative "prefix" did not move (a
+    # volatile change is not an invalidation). Else the first chain category
+    # (in CURRENT chain order) whose digest differs or is absent from
+    # `previous`; else the first PREVIOUS chain key now absent from the current
+    # chain (a vanished block is a divergence too). nil `previous` (first turn)
+    # -> nil. The returned name is a category id — PII-free by construction.
     def self.invalidation_reason(current, previous)
       return nil unless previous.is_a?(Hash)
+      return nil if current["prefix"] == previous["prefix"]
 
-      current.each_key do |name|
-        next if name == "prefix"
+      chain(current).find { |name| previous[name] != current[name] } ||
+        (chain(previous) - current.keys).first
+    end
+
+    def self.chain(map) = map.keys.take_while { |k| k != "prefix" }
 
-        return name unless previous[name] == current[name]
-      end
-      (previous.keys - current.keys).first
+    def self.category_digests(fragments)
+      fragments.group_by { |f| category(f.source) }
+               .transform_values { |frags| digest(frags.map(&:content).join("\n\n")) }
     end
 
     def self.category(source) = source.to_s.split("::").last.to_s.downcase

data/lib/insika/profile_source.rb

@@ -98,23 +98,28 @@ module Insika
         tools_allow_groups: h[:tools_allow_groups],
         skills: h[:skills],
         skills_eager: h[:skills_eager],
+        kits: h[:kits],
         context_providers: h[:context_providers],
         workflows_allow: h[:workflows_allow],
         policies: Array(h[:policies]).map(&:to_sym),
         prompt_refs: h[:prompt_refs] || [],
         limits: symbolize_limits(h[:limits]),
         approvals_required: h[:approvals_required],
+        customer_confirm: h[:customer_confirm],
         capabilities: h[:capabilities],
         # subagents: allowlist of child ids; build re-normalizes to
         # [String]. nil round-trips as nil (opt-in: NONE).
         subagents: h[:subagents],
         tools_deferred: h[:tools_deferred],
         memory: h[:memory],
+        memory_retrieval: h[:memory_retrieval],
+        shared_conversations: h[:shared_conversations],
         prompt_caching: h[:prompt_caching],
         # tool_persistence: the one opt-out flag — nil round-trips as nil (= ON);
         # only a stored explicit false turns the discipline block off.
         tool_persistence: h[:tool_persistence],
         tool_output_compression: h[:tool_output_compression],
+        fencing: h[:fencing],
         # params/model_policy: the resolver tolerates string keys from
         # the JSON round-trip (ModelResolver#normalize_params / ModelPolicy), so no
         # re-symbolization needed here.

data/lib/insika/provider_error_classifier.rb

@@ -7,11 +7,12 @@ module Insika
   # poisoned credential; a fatal is retried only after the operator fixes the
   # cause):
   #
-  #   :fatal              401/402/403/400 (auth, billing, permanent quota,
-  #                       bad request, context too long) — retrying does not help.
+  #   :fatal              401/402/403/400 (auth, billing, bad request,
+  #                       context too long) — retrying does not help.
   #   :retryable          5xx/529/socket/timeout — the same call may succeed
   #                       moments later.
-  #   :rate_limited_short a 429 that says "back off briefly" (RPM-scale).
+  #   :rate_limited_short a 429 that says "back off briefly" (RPM-scale), or a
+  #                       400 quota message RubyLLM raises as RateLimitError.
   #   :rate_limited_long  a 429 with a long retry-after — quota-scale.
   #
   # The classification is STRING-based (class names, no constant references):
@@ -98,6 +99,20 @@ module Insika
         (names & RUBY_LLM_ERROR_NAMES).any? || transport?(names)
       end
 
+      # :fatal for THIS node only: the account cannot pay (402), the key is wrong
+      # or lacks access (401/403), or the model does not exist there (404).
+      # Retrying the node never helps, but another node — another account,
+      # another model — may answer, so Reliability rotates instead of killing the
+      # turn. A 400 stays out: a malformed request fails on any node.
+      NODE_FATAL_ERROR_NAMES = %w[
+        RubyLLM::UnauthorizedError RubyLLM::PaymentRequiredError RubyLLM::ForbiddenError
+      ].freeze
+      NODE_FATAL_STATUSES = [401, 402, 403, 404].freeze
+
+      def node_fatal?(error)
+        (class_names(error) & NODE_FATAL_ERROR_NAMES).any? || NODE_FATAL_STATUSES.include?(http_status(error))
+      end
+
       # The typed ProviderError the executor stores and emits.
       def wrap(error)
         c = classify(error)

data/lib/insika/queue_policy.rb

@@ -24,7 +24,7 @@ module Insika
   #
   #   session vars["queue_mode"]   — one conversation pinned by an operator
   #   profile.limits[:<key>]       — per-agent (a PRESENT key wins, incl. nil/0 = off)
-  #   settings["queue"][<key>]     — platform default, editable in the Studio
+  #   settings["queue"][<key>]     — platform default (Studio > Settings > Burst)
   #   DEFAULTS[<key>]              — = today's behavior
   #
   # Every default is off: a bare wiring behaves exactly as it did before this
@@ -126,9 +126,14 @@ module Insika
     # "inherit the platform default". Same semantics EdgeLimiter documents at
     # `edge_limiter.rb:57`, and for the same reason: an imported pack carrying an
     # explicit null must not silently re-enable a platform behavior.
+    #
+    # The PLATFORM layer reads nil the other way round: its form (Studio > Settings >
+    # Burst) writes nil for every blank field, and blank there means "no platform
+    # default", not 0 — a blank `steer_max_messages` must not become "never steer"
+    # for the whole deploy. An agent still says "off" with an explicit 0.
     def self.pick(key, limits, platform)
       return limits[key].to_i if limits.key?(key)
-      return platform[key.to_s].to_i if platform.key?(key.to_s)
+      return platform[key.to_s].to_i unless platform[key.to_s].nil?
 
       DEFAULTS[key]
     end

data/lib/insika/refinement/proposer.rb

@@ -38,11 +38,32 @@ module Insika
 
       MAX_FINDINGS = 10
 
+      RESPONSE_SCHEMA = {
+        "type" => "object",
+        "properties" => {
+          "rationale" => { "type" => "string" },
+          "edits" => {
+            "type" => "array",
+            "items" => {
+              "type" => "object",
+              "properties" => {
+                "file" => { "type" => "string" }, "op" => { "type" => "string", "enum" => %w[replace append] },
+                "anchor" => { "type" => "string" }, "before" => { "type" => "string" },
+                "after" => { "type" => "string" },
+                "addresses" => { "type" => "array", "items" => { "type" => "string" } }
+              },
+              "required" => %w[file op after]
+            }
+          }
+        },
+        "required" => ["edits"]
+      }.freeze
+
       # The model ref, so a panel can name WHICH proposer failed without guessing.
       attr_reader :model
 
       # ask:   ->(prompt) { "<raw model text>" }, or something answering `#content`
-      #        plus `#input_tokens`/`#output_tokens` (a RubyLLM message). The second
+      #        plus RubyLLM-compatible `#tokens`. The second
       #        shape is what lets the panel's budget count what a proposal cost; a
       #        plain String stays valid and simply reports no cost, which is what
       #        every existing caller and every fake does.
@@ -63,7 +84,7 @@ module Insika
         raise Unusable, "no writable file has any content to anchor an edit in" if files.empty?
 
         answer = @ask.call(build_prompt(agent_id, Array(findings).first(MAX_FINDINGS), files, limits))
-        parsed = parse(text_of(answer))
+        parsed = parse(answer)
         parsed["proposer"] = @model
         parsed["tokens"] = tokens_of(answer)
         parsed["cached"] = cached_of(answer)
@@ -80,29 +101,33 @@ module Insika
       # reason `Evals::Runner#billed_tokens` includes it: a ceiling that cannot see
       # what the cache served is not a ceiling on what was sent.
       def tokens_of(answer)
-        return nil unless answer.respond_to?(:input_tokens) && answer.respond_to?(:output_tokens)
+        return nil unless answer.respond_to?(:tokens)
 
-        total = answer.input_tokens.to_i + answer.output_tokens.to_i + cached_of(answer).to_i
+        usage = answer.tokens
+        total = usage.input.to_i + usage.output.to_i + usage.cache_read.to_i + usage.cache_write.to_i
         total.positive? ? total : nil
       end
 
       def cached_of(answer)
-        return nil unless answer.respond_to?(:cached_tokens)
+        return nil unless answer.respond_to?(:tokens)
 
-        cached = answer.cached_tokens.to_i
+        cached = answer.tokens.cache_read.to_i
         cached.positive? ? cached : nil
       end
 
-      # JSON or nothing. ````json` fences are the common wrapper and stripping them is
-      # not leniency — the payload inside is still parsed strictly, so a model that
-      # improvises a schema fails here instead of producing half a candidate.
-      def parse(raw)
-        body = raw.strip.gsub(/\A```(?:json)?\s*|\s*```\z/, "")
-        first = body.index("{")
-        last = body.rindex("}")
-        raise Unusable, "the proposer answered with no JSON object" if first.nil? || last.nil? || last < first
-
-        parsed = JSON.parse(body[first..last])
+      # Native responses own JSON parsing. Only injected text asks retain the
+      # existing prose/fence extraction contract.
+      def parse(answer)
+        if answer.respond_to?(:parsed)
+          parsed = answer.parsed
+        else
+          body = text_of(answer).strip.gsub(/\A```(?:json)?\s*|\s*```\z/, "")
+          first = body.index("{")
+          last = body.rindex("}")
+          raise Unusable, "the proposer answered with no JSON object" if first.nil? || last.nil? || last < first
+
+          parsed = JSON.parse(body[first..last])
+        end
         raise Unusable, "the proposer's JSON is not an object" unless parsed.is_a?(Hash)
         raise Unusable, "the proposer's JSON carries no `edits`" unless parsed["edits"].is_a?(Array)
 
@@ -254,7 +279,7 @@ module Insika
         llm ||= RubyLLM
         lambda do |prompt|
           llm.chat(model: model, provider: provider, assume_model_exists: true)
-             .with_temperature(0).ask(prompt)
+             .with_temperature(0).with_schema("schema" => Proposer::RESPONSE_SCHEMA, "strict" => false).ask(prompt)
         end
       end
     end

data/lib/insika/reliability.rb

@@ -6,8 +6,9 @@ module Insika
   # the circuit breaker — all as DATA on `AgentProfile#reliability`, never a
   # parallel code path. The failure classification is B9's
   # (ProviderErrorClassifier): ONLY :retryable / :rate_limited_* ever retry or
-  # rotate; a :fatal is re-raised immediately (a poisoned credential must not
-  # hammer N models).
+  # rotate; a :fatal is re-raised immediately (a malformed request fails on any
+  # model) — unless it is fatal only for that node (402/401/403/404:
+  # `ProviderErrorClassifier.node_fatal?`), which skips to the next node.
   #
   # Each ATTEMPT is a fresh chat built by the caller (the coordinator yields the
   # selection): a failed `ask` leaves its user message in the chat, so re-asking
@@ -100,7 +101,15 @@ module Insika
             # never rotated).
             retryable = retryable_failure?(e)
             raise unless retryable
-            raise if kind_of(e) == :fatal && !e.is_a?(Insika::TimeoutError)
+            if kind_of(e) == :fatal && !e.is_a?(Insika::TimeoutError)
+              # Fatal for THIS node only (no balance, bad key, unknown model):
+              # skip to the next node at once — no retry, no backoff, no breaker
+              # bump (an open primary circuit fails fast WITHOUT rotating).
+              raise unless ProviderErrorClassifier.node_fatal?(e) && node != nodes.last
+
+              record_failure(tenant, selection, nil, e, agent)
+              break
+            end
 
             record_failure(tenant, selection, breaker, e, agent)
             # the last attempt of the last node re-raises; otherwise back off

data/lib/insika/router/app.rb

@@ -49,7 +49,7 @@ module Insika
         return health_response if req.request_method == "GET" && segments == ["up"]
 
         raw_body = read_body(env)
-        backend = pick_backend(req.request_method, segments, raw_body)
+        backend = pick_backend(req, segments, raw_body)
         return unavailable_response if backend.nil?
 
         proxy(req, backend, raw_body)
@@ -57,18 +57,20 @@ module Insika
 
       private
 
-      def pick_backend(method, segments, raw_body)
+      def pick_backend(req, segments, raw_body)
         backends = @pool.backends
         return nil if backends.empty?
 
-        key = session_key(method, segments, raw_body)
+        key = session_key(req, segments, raw_body)
         return @pool.ring.backend_for(key) if key
 
         @rr_index = (@rr_index + 1) % backends.size
         backends[@rr_index]
       end
 
-      def session_key(method, segments, raw_body)
+      def session_key(req, segments, raw_body)
+        method = req.request_method
+        return SessionKey.extract(method, segments, body: -> {}, query: req.GET) if method == "GET"
         return nil if raw_body.nil?
 
         if raw_body.bytesize > @body_max_bytes
@@ -77,7 +79,14 @@ module Insika
           return nil
         end
 
-        SessionKey.extract(method, segments, body: -> { JSON.parse(raw_body) })
+        SessionKey.extract(method, segments, body: -> { parse_body(req, raw_body) })
+      end
+
+      # JSON for the machine routes; the Studio's forms post urlencoded.
+      def parse_body(req, raw_body)
+        return Rack::Utils.parse_query(raw_body) if req.media_type == "application/x-www-form-urlencoded"
+
+        JSON.parse(raw_body)
       end
 
       # Reads the WHOLE body (it must be forwarded intact) — `body_max_bytes`