insika 0.9.0 → 1.0.1

data/lib/insika/mcp_live_tool.rb

@@ -1,43 +1,89 @@
 # frozen_string_literal: true
 
+require "json"
 require "ruby_llm"
 
 module Insika
-  # One live MCP tool. `name`/`description`/`params_schema`
+  # One live MCP tool. `name`/`description`/`parameters_schema`
   # come from the CACHED descriptor (McpStore#tools_cache — no I/O to build
   # this instance, same cost as any other tool the registry hands out).
   # `#execute` is the only thing that touches the network, calling through
-  # `client_for` (Insika::McpToolRegistry's memoized, started client — this
-  # class never builds or starts one itself) into the gem's own
-  # `RubyLLM::MCP::Tool#execute`, which already unwraps `content[].text` and
+  # `client_for` (Insika::McpToolRegistry's memoized, lazy, per-conversation client) into
+  # `RubyLLM::MCP::Tool#call`, which already unwraps `content[].text` and
   # turns `isError` into `{error:}`.
   #
   # Like every tool in this codebase, `#execute` NEVER raises: a connection
   # or protocol failure becomes `{error:}`, the model's normal failure path
   # (see Tools::DataDefinedTool's own rule).
   class McpLiveTool < RubyLLM::Tool
-    def initialize(instance_name:, tool:, client_for:)
+    # `name:` is what the model calls (the registry's instance-qualified name);
+    # the server is still asked for its own tool name.
+    def initialize(instance_name:, tool:, client_for:, overrides: {}, name: tool["name"])
       @instance_name = instance_name
       @tool = tool
+      @name = name
       @client_for = client_for
+      @evidence = overrides["evidence"] && Insika::Evidence::Spec.parse(overrides["evidence"])
+      @requires_evidence = Insika::ToolDefinition.normalize_requires_evidence(
+        overrides["requires_evidence"], top_level_params
+      )
       super()
     end
 
-    def name = @tool["name"]
+    def name = @name
     def description = @tool["description"].to_s
 
-    def params_schema
+    # The two questions the envelope asks any tool: what of this result is
+    # evidence, and which of these parameters may only carry an id some tool
+    # already returned. A server cannot answer either — it does not know what the
+    # deployment trusts — so they come from the instance's own configuration and
+    # are nil for every tool nobody configured, which is what they were before.
+    attr_reader :evidence, :requires_evidence
+
+    def parameters_schema
       schema = @tool["inputSchema"]
       schema.nil? || schema.empty? ? { "type" => "object", "properties" => {} } : schema
     end
 
+    # The conversation this instance serves, deposited by ToolAssembly. An MCP
+    # server keeps state per MCP session (a target store, a pending
+    # confirmation token), so each conversation gets its own client.
+    def turn_context=(ctx)
+      @session_id = ctx && (ctx[:session_id] || ctx["session_id"])
+    end
+
     def execute(**params)
-      live = @client_for.call.tool(@tool["name"])
+      live = @client_for.call(@session_id).tools.find { |tool| tool.name == @tool["name"] }
       raise Insika::NotFoundError, "tool '#{@tool["name"]}' no longer offered" if live.nil?
 
-      live.execute(**params)
+      result = live.call(**params)
+      # Hand the envelope what a chat would send the model (text, JSON of the
+      # structured content, or text plus attachments), not the gem's Result.
+      parsed(result.is_a?(RubyLLM::MCP::Result) ? result.content : result)
     rescue StandardError => e
       { error: "MCP instance '#{@instance_name}' tool '#{@tool["name"]}' failed: #{e.message}" }
     end
+
+    private
+
+    # An MCP result arrives as a String, text plus attachments (an Array), or
+    # {error:}. Only a tool someone declared evidence for is
+    # parsed into the object the extractor can dig into; everywhere else the result
+    # reaches the model exactly as it did before.
+    def parsed(result)
+      return result unless @evidence && result.is_a?(String)
+
+      object = begin
+        JSON.parse(result)
+      rescue JSON::ParserError
+        nil
+      end
+      object.is_a?(Hash) ? object : result
+    end
+
+    def top_level_params
+      properties = parameters_schema["properties"] || parameters_schema[:properties] || {}
+      properties.keys.map(&:to_s)
+    end
   end
 end

data/lib/insika/mcp_store.rb

@@ -94,12 +94,43 @@ module Insika
         "headers" => reconcile_hash(h[:headers], existing && existing["headers"]),
         # editing an instance's connection details doesn't change its discovered
         # tools -> preserved across upsert; only set_tools_cache writes it.
-        "tools_cache" => (existing && existing["tools_cache"]) || []
+        "tools_cache" => (existing && existing["tools_cache"]) || [],
+        # WHAT EACH TOOL MEANS to the engine: which of its results are evidence,
+        # and which of its parameters may only carry an id some tool returned.
+        # A server describes what its tools DO; only the deployment can say what
+        # they are worth trusting with. An edit that does not mention them keeps
+        # what is there — the same rule `env` and `headers` follow.
+        "tool_overrides" => (h.key?(:tools) ? tool_overrides(h[:tools]) : nil) ||
+                            (existing && existing["tool_overrides"]) || {}
       }
       @cs.put(SCOPE, name, record)
       mask(record)
     end
 
+    # { "add_to_cart" => { "requires_evidence" => ["product_id"] },
+    #   "search_products" => { "evidence" => { "kind" => "products", … } } }
+    #
+    # Refused HERE, never at the turn: an `evidence:` typo that survived to turn
+    # time would extract nothing and the gate below it would block every write.
+    def tool_overrides(raw)
+      return nil if raw.nil?
+      raise Insika::ValidationError, "mcp tools must be a mapping of tool name -> overrides" unless raw.is_a?(Hash)
+
+      Coercion.deep_stringify(raw).to_h do |tool, over|
+        raise Insika::ValidationError, "mcp tools['#{tool}'] must be a mapping" unless over.is_a?(Hash)
+
+        unknown = over.keys - %w[evidence requires_evidence]
+        unless unknown.empty?
+          raise Insika::ValidationError,
+                "mcp tools['#{tool}']: unknown key(s) #{unknown.join(", ")} — known: evidence, requires_evidence"
+        end
+
+        params = Array(over["requires_evidence"]).map(&:to_s).reject(&:empty?)
+        [tool.to_s, { "evidence" => over["evidence"] && Insika::Evidence::Spec.parse(over["evidence"]).to_h,
+                      "requires_evidence" => (params unless params.empty?) }.compact]
+      end
+    end
+
     # -> bool (did it exist?).
     def delete(name) = @cs.delete(SCOPE, name.to_s)
 

data/lib/insika/mcp_tool_registry.rb

@@ -11,14 +11,30 @@ module Insika
   # `refresh` is the ONLY thing that talks to a server ahead of time: it
   # connects, lists live, and writes the result back to tools_cache (display/
   # doctor). Calling a tool never depends on that cache — Insika::McpLiveTool
-  # always goes through the live, memoized client (and RubyLLM::MCP::Client
+  # always goes through the live, memoized client (and RubyLLM::MCP
   # does its own real `tools/list` on ITS first use per instance, regardless
   # of whether `refresh` ever ran).
   class McpToolRegistry
-    def initialize(mcp_store:, client_factory: Insika::McpClient.method(:for))
+    # Providers reject a tool name longer than this.
+    MAX_TOOL_NAME = 64
+
+    # The name the model and the agent's allowlist see: the instance, then the
+    # server's tool. Two servers offering the same tool (a store's prod and
+    # staging) stay two tools, each reaching its own instance.
+    def self.tool_name(instance, tool)
+      "#{instance.to_s.downcase.gsub(/[^a-z0-9]+/, '_')}__#{tool}"
+    end
+
+    # Live clients kept per process. Past this, the least recently used one is
+    # closed; its conversation reconnects on its next call, as a NEW MCP session.
+    # ponytail: count cap, not idle TTL — add a TTL if idle sockets pile up.
+    MAX_CLIENTS = 200
+
+    def initialize(mcp_store:, client_factory: Insika::McpClient.method(:for), max_clients: MAX_CLIENTS)
       @mcp_store = mcp_store
       @client_factory = client_factory
-      @clients = {}
+      @max_clients = max_clients
+      @clients = {} # [instance, conversation] -> client, oldest use first
       @mutex = Mutex.new
     end
 
@@ -29,7 +45,7 @@ module Insika
 
     # Connects to `name` LIVE, lists its tools, and writes McpStore#tools_cache.
     # ALWAYS drops any memoized client first and rebuilds from the current
-    # record: a stdio process can be `alive?` (still running) yet permanently
+    # record: a stdio process can still be running yet permanently
     # broken (e.g. wrong transport args — see grafana-stg gotcha), and an
     # edited command/url/env must take effect without a process restart —
     # there's no SSH into a Railway dyno to do that by hand.
@@ -43,7 +59,10 @@ module Insika
 
       evict(record["name"])
       client = client_for(record)
-      discovered = client.tools.map { |t| { "name" => t.name, "description" => t.description, "inputSchema" => t.params_schema } }
+      discovered = client.tools.map do |tool|
+        { "name" => tool.name, "description" => tool.description, "inputSchema" => tool.parameters_schema,
+          "annotations" => { "readOnlyHint" => tool.read_only? } }
+      end
       @mcp_store.set_tools_cache(name, discovered)
       discovered
     end
@@ -55,24 +74,30 @@ module Insika
     # NEXT tool call or refresh, no process restart required (there's no way
     # to restart a process by hand on a Railway dyno).
     def evict(name)
-      client = @mutex.synchronize { @clients.delete(name.to_s) }
-      client&.stop
-    rescue StandardError
-      nil # best-effort teardown of a possibly already-dead process
+      gone = @mutex.synchronize do
+        keys = @clients.keys.select { |instance, _| instance == name.to_s }
+        keys.map { |key| @clients.delete(key) }
+      end
+      gone.each { |client| close_quietly(client) }
     end
 
     private
 
     def entries_for(record)
-      Array(record["tools_cache"]).map { |tool| entry_for(record, tool) }
+      Array(record["tools_cache"]).filter_map do |tool|
+        name = self.class.tool_name(record["name"], tool["name"])
+        next entry_for(record, tool, name) if name.length <= MAX_TOOL_NAME
+
+        warn "[mcp] skipping '#{name}': longer than #{MAX_TOOL_NAME} characters; shorten the instance name"
+      end
     end
 
-    def entry_for(record, tool)
+    def entry_for(record, tool, name)
       instance = record["name"]
       Insika::Registry::Entry.new(
-        name: tool["name"], plugin: "mcp:#{instance}",
+        name: name, plugin: "mcp:#{instance}",
         metadata: { optional: false, side_effect: !read_only?(tool), group: "mcp:#{instance}", tags: [] },
-        factory: -> { build_tool(record, tool) }
+        factory: -> { build_tool(record, tool, name) }
       )
     end
 
@@ -80,28 +105,46 @@ module Insika
     # (`annotations.readOnlyHint`): a write is never re-run on resume and runs
     # serially within the session; a declared read keeps `tool_concurrency`.
     def read_only?(tool)
-      Coercion.truthy?(tool.dig("annotations", "readOnlyHint"))
+      tool.dig("annotations", "readOnlyHint") == true
     end
 
     # Lazy require (McpLiveTool < RubyLLM::Tool pulls in ruby_llm) — kept out
     # of insika.rb load-time, loaded on the 1st instance (turn time), same
     # discipline as OverlayToolRegistry#build_tool for data-tools.
-    def build_tool(record, tool)
+    def build_tool(record, tool, name)
       require_relative "mcp_live_tool"
-      Insika::McpLiveTool.new(instance_name: record["name"], tool: tool, client_for: -> { client_for(record) })
+      Insika::McpLiveTool.new(instance_name: record["name"], tool: tool, name: name,
+                              overrides: record.dig("tool_overrides", tool["name"]) || {},
+                              client_for: ->(session_id = nil) { client_for(record, session_id) })
     end
 
-    # A started, MEMOIZED client for `record` — one real connection per
-    # instance name, reused across calls/turns. Raises on a gated/unreachable
-    # instance; only called from `refresh` and from a running McpLiveTool's
-    # `#execute` (which rescues) — never from `entries`/`build_tool`, so a
-    # downed server never breaks turn ASSEMBLY, only that tool's own call.
-    def client_for(record)
-      @mutex.synchronize do
-        client = (@clients[record["name"]] ||= @client_factory.call(record))
-        client.start unless client.alive?
-        client
+    # A lazy, MEMOIZED client for `record` — one per (instance, conversation),
+    # reused across that conversation's turns. The server ties its state to the
+    # MCP session (Mcp-Session-Id): a client shared by every conversation leaked
+    # one chat's target store and confirmation tokens into another. A stdio
+    # instance stays one shared process — a process per chat is too costly.
+    # Raises on a gated/unreachable instance; only called from `refresh` and
+    # from a running McpLiveTool's `#execute` (which rescues) — never from
+    # `entries`/`build_tool`, so a downed server never breaks turn ASSEMBLY,
+    # only that tool's own call.
+    def client_for(record, session_id = nil)
+      session_id = nil if record["transport"].to_s == "stdio"
+      key = [record["name"], session_id&.to_s]
+      stale = nil
+      client = @mutex.synchronize do
+        found = @clients.delete(key) || @client_factory.call(record)
+        @clients[key] = found # re-insert: most recently used goes last
+        stale = @clients.shift.last if @clients.size > @max_clients
+        found
       end
+      close_quietly(stale) if stale
+      client
+    end
+
+    def close_quietly(client)
+      client.close
+    rescue StandardError
+      nil # best-effort teardown of a possibly already-dead process
     end
   end
 end

data/lib/insika/media.rb

@@ -93,9 +93,9 @@ module Insika
     # when the turn first carries audio. `stt_prompt` is the Whisper-family
     # vocabulary hint (product names, brand terms) — OPERATOR config
     # (agent profile / deployment env), never customer input.
-    def self.default_transcriber(stt_model:, stt_language: nil, stt_prompt: nil)
+    def self.default_transcriber(stt_model:, stt_language: nil, stt_prompt: nil, context: nil)
       lambda do |url|
-        fetch_and_transcribe(url, model: stt_model, language: stt_language, prompt: stt_prompt)
+        fetch_and_transcribe(url, model: stt_model, language: stt_language, prompt: stt_prompt, context: context)
       end
     end
 
@@ -110,7 +110,7 @@ module Insika
     # RubyLLM raises ArgumentError when it's true without an explicit
     # `provider` (see ModelSelection#assume_model_exists?), and `stt_model` here
     # is a bare ref like `utility_model` elsewhere — the registry resolves it.
-    def self.fetch_and_transcribe(url, model:, language:, prompt: nil)
+    def self.fetch_and_transcribe(url, model:, language:, prompt: nil, context: nil)
       require "net/http"
       require "uri"
       require "ruby_llm" # lazy — the core loads without it (load-guard)
@@ -120,6 +120,7 @@ module Insika
       options = { model: model }
       options[:language] = language if language
       options[:prompt] = prompt if prompt
+      options[:context] = context if context
       Tempfile.create(["insika-media-", File.extname(filename_for(url).to_s)]) do |file|
         file.binmode
         file.write(bytes)
@@ -128,6 +129,23 @@ module Insika
       end
     end
 
+    # Durable attachment bytes from a checkpoint; hydrate only at the gem boundary.
+    def self.hydrate_attachment(value)
+      return value unless value.is_a?(Hash)
+      require 'base64'
+      require 'stringio'
+      require 'ruby_llm'
+      unless (value.keys - %w[base64 filename]).empty? && value['base64'].is_a?(String) && value['filename'].is_a?(String)
+        raise Insika::MediaError, 'invalid stored attachment'
+      end
+      raise Insika::MediaError, 'stored attachment too large' if value['base64'].bytesize > 14*1024*1024
+      bytes = Base64.strict_decode64(value['base64'])
+      raise Insika::MediaError, 'stored attachment too large' if bytes.bytesize > MAX_DOCUMENT_BYTES
+      RubyLLM::Attachment.new(StringIO.new(bytes), filename: value['filename'])
+    rescue ArgumentError
+      raise Insika::MediaError, 'invalid stored attachment'
+    end
+
     # An inbound URL -> a RubyLLM::Attachment over bytes WE fetched (egress-
     # guarded, size-capped — the `media_attachment` recipe). Shared by the
     # Executor (inbound image/document parts) and `Output.generate_image`
@@ -201,8 +219,7 @@ module Insika
     # behind lazy requires:
     #  · image — RubyLLM.paint (the gem has vision AND painting), billed
     #    tokens merged into the turn's usage like any ask;
-    #  · tts — RubyLLM still has NO speech API (as of 1.16.0), so the default
-    #    is a thin POST to the OpenAI-compatible `<base>/audio/speech`
+    #  · tts — a capped POST to the OpenAI-compatible `<base>/audio/speech`
     #    endpoint (base + key from the provider config the chat uses — a
     #    deployment pointing OpenAI at a gateway keeps TTS pointing there).
     #    OpenAI's speech API reports no token usage; the part carries the
@@ -256,8 +273,8 @@ module Insika
 
           enforce_embedded_size!(data, "generated image")
           mime = image.respond_to?(:mime_type) ? image.mime_type : nil
-          model_id = image.respond_to?(:model_id) ? image.model_id : nil
-          usage = image.respond_to?(:usage) ? token_usage(image.usage) : {}
+          model_id = image.model
+          usage = { input_tokens: image.tokens.input, output_tokens: image.tokens.output }.compact
           part = { "type" => "image", "mime_type" => presence(mime) || "image/png",
                    "base64" => data, "model" => presence(model_id) }
           [part.compact, usage]
@@ -292,20 +309,24 @@ module Insika
           req.body = JSON.generate(model: model, voice: voice, input: text.to_s,
                                    response_format: format)
           opts = { use_ssl: uri.scheme == "https", open_timeout: 30, read_timeout: 60 }
+          # RubyLLM 2.0 buffers non-audio/error responses without yielding chunks.
+          # Keep this bounded transport until native speech caps every response.
           bytes = Net::HTTP.start(uri.host, uri.port, opts) do |http|
-            resp = http.request(req)
-            raise Insika::MediaError, "TTS HTTP #{resp.code}" unless resp.is_a?(Net::HTTPSuccess)
-
-            # stream into the cap — a rogue/broken endpoint must not grow the
-            # process past MAX_EMBEDDED_BYTES before the refusal.
             buf = +"".b
-            resp.read_body do |chunk|
-              buf << chunk
-              break if buf.bytesize > MAX_EMBEDDED_BYTES
+            http.request(req) do |resp|
+              raise Insika::MediaError, "TTS HTTP #{resp.code}" unless resp.is_a?(Net::HTTPSuccess)
+
+              resp.read_body do |chunk|
+                size = buf.bytesize + chunk.bytesize
+                if size > MAX_EMBEDDED_BYTES
+                  raise Insika::MediaError,
+                        "synthesized speech too large to embed (#{size} bytes > #{MAX_EMBEDDED_BYTES})"
+                end
+                buf << chunk
+              end
             end
             buf
           end
-          enforce_embedded_size!(bytes, "synthesized speech")
           part = { "type" => "audio", "mime_type" => mime_for(format), "base64" => Base64.strict_encode64(bytes), "model" => model }
           [part.compact, {}]
         rescue URI::InvalidURIError
@@ -352,14 +373,6 @@ module Insika
           Insika::Media.url_attachment(url, max_bytes: Insika::Media::MAX_IMAGE_BYTES)
         end
 
-        def token_usage(raw)
-          usage = raw.is_a?(Hash) ? raw : {}
-          {
-            input_tokens: usage[:input_tokens] || usage["input_tokens"] || usage["prompt_tokens"],
-            output_tokens: usage[:output_tokens] || usage["output_tokens"] || usage["completion_tokens"]
-          }.compact
-        end
-
         def mime_for(format)
           { "mp3" => "audio/mpeg", "opus" => "audio/opus", "aac" => "audio/aac",
             "wav" => "audio/wav", "flac" => "audio/flac" }[format.to_s] || "audio/mpeg"
@@ -379,4 +392,4 @@ module Insika
       end
     end
   end
-end
+end

data/lib/insika/memory_store.rb

@@ -155,9 +155,10 @@ module Insika
     # "memory:chat:<tenant>:<id>"). The scope enumeration is the Store's — no
     # session-derived list, so a customer cell whose session was already
     # deleted is still purged. ONE transaction for the whole tenant (the repo
-    # rule): the scope enumeration and every delete see the same snapshot, so a
-    # customer cell born mid-purge cannot slip through a deletion that reported
-    # success. -> count of records purged.
+    # rule): the purge commits or fails whole. On SQLite, whose transactions
+    # run one at a time, a cell cannot be written mid-purge at all; on a backend
+    # with concurrent writers a cell written while the purge runs lands after it
+    # (a later write, which a later purge removes). -> count of records purged.
     def purge_tenant(tenant)
       cell = scope_for(tenant)
       @store.transaction do

data/lib/insika/memory_trim.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Insika
+  # Hands freed memory back to the OS once a worker goes quiet. After a burst, glibc
+  # keeps what the turns freed inside its malloc arenas and the process stays at its
+  # peak until something calls malloc_trim — a full GC alone returns nothing. On a
+  # quiet pass (no turn in flight, enough allocated since the last trim) this runs a
+  # full GC and then malloc_trim(0).
+  #
+  # A no-op where malloc_trim does not exist (macOS, musl, a jemalloc LD_PRELOAD
+  # returns 0) or where `fiddle` is not in the bundle: it is not a gem dependency,
+  # the reference deployment adds it to its Gemfile.
+  class MemoryTrim
+    INTERVAL = 60 # seconds between checks
+    MIN_ALLOCATED = 1_000_000 # objects allocated since the last trim; less is not worth a full GC
+
+    def self.malloc_trim
+      require "fiddle"
+      fn = Fiddle::Function.new(Fiddle::Handle::DEFAULT["malloc_trim"], [Fiddle::TYPE_SIZE_T], Fiddle::TYPE_INT)
+      -> { fn.call(0) }
+    rescue LoadError, StandardError # no fiddle, or no malloc_trim symbol (Fiddle::DLError)
+      nil
+    end
+
+    def initialize(executor:, trim: self.class.malloc_trim, allocated: -> { GC.stat(:total_allocated_objects) })
+      @executor = executor
+      @trim = trim
+      @allocated = allocated
+      @last = @allocated.call
+    end
+
+    def enabled? = !@trim.nil?
+
+    # One check. -> true when it trimmed.
+    def run_once
+      return false unless @executor.in_flight.empty?
+      return false if @allocated.call - @last < MIN_ALLOCATED
+
+      GC.start
+      @trim.call
+      @last = @allocated.call
+      true
+    end
+
+    def start(parent:, interval: INTERVAL)
+      return false unless enabled?
+
+      parent.async do |t|
+        t.annotate("insika-memory-trim")
+        loop do
+          sleep(interval)
+          run_once
+        rescue StandardError => e
+          warn "[memory_trim] #{e.class}: #{e.message}"
+        end
+      end
+      true
+    end
+  end
+end

data/lib/insika/middleware.rb

@@ -35,11 +35,20 @@ module Insika
       self
     end
 
-    def call(state, &terminal)
-      chain = @middlewares.reverse.reduce(terminal) do |nxt, mw|
+    # Paid retrieval prepares context inside the leading edge limiter. Other
+    # middleware still receives the completed context and policy resolution.
+    def call(state, prepare: nil, &terminal)
+      edge = @middlewares.first if prepare && @middlewares.first.is_a?(EdgeLimiter)
+      links = edge ? @middlewares.drop(1) : @middlewares
+      chain = links.reverse.reduce(terminal) do |nxt, mw|
         proc { |s| mw.call(s, &nxt) }
       end
-      chain.call(state)
+      if edge
+        edge.call(state, prepare: prepare, &chain)
+      else
+        prepare&.call(state)
+        chain.call(state)
+      end
     end
   end
 end