insika 0.8.0 → 1.0.1

data/lib/insika/mcp_client.rb

@@ -1,94 +1,58 @@
 # frozen_string_literal: true
 
 module Insika
-  # Builds a live MCP client for an McpStore record. The ONE seam
-  # between Insika and the transport gem: `ruby_llm-mcp` speaks stdio,
-  # Streamable HTTP and SSE with the full lifecycle (initialize handshake,
-  # session-id, notifications) — Insika stops maintaining its own protocol
-  # client. Swapping the gem later (e.g. to modelcontextprotocol/ruby-sdk)
-  # touches only this file.
-  #
-  # `require "ruby_llm/mcp"` is LAZY, done here rather than at `require
-  # "insika"` time (spec/insika/load_guard_spec.rb): the gem drags in
-  # ruby_llm + httpx, the same opt-in-cost discipline as every other provider
-  # surface.
-  #
-  # Client LIFECYCLE (start/stop, registering the child process with
-  # Insika::Shutdown so it dies on SIGTERM) belongs to whoever holds the
-  # client across calls — the live tool registry, later work. `for` itself
-  # returns an unstarted client (`start: false`); building one is cheap and
-  # side-effect-free.
+  # Maps persisted MCP configuration to RubyLLM's native, lazy client.
+  # Insika retains the stdio opt-in and deployment egress policy.
   module McpClient
-    # A stdio instance is arbitrary command execution by config — refused
-    # unless the operator opted in (config-over-convention, same pattern as
-    # the egress envs).
     class StdioDisabled < Insika::Error; end
 
     module_function
 
-    # `record` — the RAW McpStore record (get_raw/all_raw; never the masked
-    # one — a masked record's credentials are the __OCULTO__ sentinel, not
-    # something a client can connect with).
-    # -> RubyLLM::MCP::Client, not started. Raises StdioDisabled (stdio, gate
-    # off), Insika::Error (http/sse, egress-blocked url) or
-    # Insika::ValidationError (unknown transport).
     def for(record, env_reader: Insika::EnvSchema, egress: Insika::EgressGuard)
-      require "ruby_llm/mcp"
-      apply_origin_header_fix!
+      require "ruby_llm"
 
       case record["transport"].to_s
       when "stdio" then stdio_client(record, env_reader: env_reader)
-      when "http" then http_client(record, :streamable_http, egress: egress)
-      when "sse" then http_client(record, :sse, egress: egress)
+      when "http" then http_client(record, egress: egress, env_reader: env_reader)
+      when "sse"
+        raise Insika::ValidationError,
+              "MCP instance '#{record['name']}' uses legacy SSE; configure its Streamable HTTP endpoint instead"
       else
         raise Insika::ValidationError,
-              "MCP instance '#{record["name"]}' has an unknown transport: #{record["transport"].inspect}"
+              "MCP instance '#{record['name']}' has an unknown transport: #{record['transport'].inspect}"
       end
     end
 
+    # The operator registers an MCP URL and the model cannot change it, so the
+    # host allowlist (which pins model-shaped data-tool requests) only pins
+    # private destinations: a public server needs no redeploy to be added.
+    def egress_options(env_reader)
+      hosts = env_reader.read("INSIKA_EGRESS_HOSTS").to_s.split(",").map(&:strip).reject(&:empty?)
+      { allow_http: env_reader.truthy?(env_reader.read("INSIKA_EGRESS_ALLOW_HTTP")),
+        allow_private: env_reader.truthy?(env_reader.read("INSIKA_EGRESS_ALLOW_PRIVATE")),
+        host_allowlist: (hosts unless hosts.empty?), pin_private_only: true }.compact
+    end
+
     def stdio_client(record, env_reader:)
       unless env_reader.truthy?(env_reader.read("INSIKA_MCP_STDIO"))
         raise StdioDisabled,
-              "MCP instance '#{record["name"]}' is stdio (arbitrary command execution by config) — " \
+              "MCP instance '#{record['name']}' is stdio (arbitrary command execution by config) — " \
               "set INSIKA_MCP_STDIO=1 to allow it to start"
       end
 
-      RubyLLM::MCP.client(
-        name: record["name"], transport_type: :stdio, start: false,
-        config: { command: record["command"], args: Array(record["args"]), env: record["env"] || {} }
-      )
+      RubyLLM.mcp(name: record["name"], command: [record["command"], *Array(record["args"])],
+                  env: record["env"] || {})
     end
 
-    def http_client(record, transport_type, egress:)
+    def http_client(record, egress:, env_reader:)
       url = record["url"]
-      reason = egress.violation(url)
+      reason = egress.violation(url, **egress_options(env_reader))
       raise Insika::Error, "MCP target blocked: #{reason}" if reason
-
-      RubyLLM::MCP.client(
-        name: record["name"], transport_type: transport_type, start: false,
-        config: { url: url, headers: record["headers"] || {} }
-      )
-    end
-
-    # https://github.com/patvice/ruby_llm-mcp/issues/140 (open, unfixed as of
-    # 1.0.1): StreamableHTTP#build_common_headers sets `Origin` to the MCP
-    # endpoint's OWN url (path included) on every request. That's invalid per
-    # RFC 6454 §7 (Origin is scheme+host[+port], never a path) and unneeded —
-    # a server-to-server client has no browser Origin to report, and the
-    # reference TS/Python SDKs never send one. No allowlist can ever match a
-    # value that carries a path, so any server enforcing the spec's
-    # DNS-rebinding Origin check (GitHub's remote MCP, Grafana, Metabase, ...)
-    # rejects every request. Same prepend the issue's own author ships in
-    # production. `Module#prepend` no-ops if the module is already in the
-    # ancestor chain, so calling this on every `for` is cheap and safe.
-    def apply_origin_header_fix!
-      RubyLLM::MCP::Native::Transports::StreamableHTTP.prepend(OriginHeaderFix)
-    end
-
-    module OriginHeaderFix
-      def build_common_headers
-        super.except("Origin")
+      unless RubyLLM::MCP::HTTP.secure?(url)
+        raise Insika::ValidationError, "Native MCP requires HTTPS without URL credentials, except on loopback hosts"
       end
+
+      RubyLLM.mcp(name: record["name"], url: url, headers: record["headers"] || {})
     end
   end
 end

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)
 
@@ -135,7 +166,7 @@ module Insika
 
     def http_like?(transport) = %w[http sse].include?(transport.to_s)
 
-    # -> [{"name","description","inputSchema"}] string-keyed, dropping any
+    # -> [{"name","description","inputSchema"[,"annotations"]}] string-keyed, dropping any
     # entry without a name (nothing to register a Registry::Entry under).
     def normalize_tools_cache(tools)
       Array(tools).filter_map do |t|
@@ -143,7 +174,10 @@ module Insika
         name = presence(h["name"])
         next nil if name.nil?
 
-        { "name" => name, "description" => h["description"].to_s, "inputSchema" => h["inputSchema"] || {} }
+        cached = { "name" => name, "description" => h["description"].to_s, "inputSchema" => h["inputSchema"] || {} }
+        # the server's own hints (readOnlyHint decides side_effect at registration)
+        cached["annotations"] = h["annotations"] if h["annotations"].is_a?(Hash)
+        cached
       end
     end
 

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,46 +74,77 @@ 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}",
-        metadata: { optional: false, side_effect: true, group: "mcp:#{instance}", tags: [] },
-        factory: -> { build_tool(record, tool) }
+        name: name, plugin: "mcp:#{instance}",
+        metadata: { optional: false, side_effect: !read_only?(tool), group: "mcp:#{instance}", tags: [] },
+        factory: -> { build_tool(record, tool, name) }
       )
     end
 
+    # An MCP tool is a side effect unless its server says otherwise
+    # (`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)
+      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

@@ -42,6 +42,18 @@ module Insika
     # ids live in a different namespace in practice.
     SESSION_TAG = "chat"
 
+    # The ONE memory-cell rule, read by the turn (Executor) and by whoever
+    # writes a cell the turn must find (SeedSession): a customer -> the
+    # "[tenant:]customer" cell; otherwise the tenant's cell; otherwise the marked
+    # per-session cell "chat:<session id>" (nil for a one-shot turn with no
+    # session — the store applies _default).
+    def self.scope_for(tenant:, customer:, session_id:)
+      return [tenant, customer].compact.join(":") if customer
+      return tenant if tenant
+
+      "#{SESSION_TAG}:#{session_id}" if session_id
+    end
+
     Fact = Data.define(:key, :value, :origin, :created_at, :updated_at, :expires_at)
     Note = Data.define(:id, :text, :created_at)
 
@@ -143,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