insika 0.9.0 → 1.0.1

data/lib/insika/telemetry.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "logger"
+
 require "async"
 require_relative "telemetry/pricing"
 require_relative "telemetry/recorder"
@@ -15,7 +17,7 @@ module Insika
   # (`OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_TRACES_EXPORTER`). The destination/protocol
   # follows the OTEL SDK's default config (env) — SigNoz/Tempo/Jaeger/Collector. The
   # OTEL_* keys are the OpenTelemetry SDK's own env and stay verbatim; only our opt-in
-  # toggle is renamed (INSIKA_OTEL, with the HARNESS_OTEL alias still read).
+  # toggle is INSIKA_OTEL.
   #
   # Metrics ride the same switch and the SAME standard env: the SDK
   # registers a periodic metric reader when the OTLP metrics exporter is loadable,
@@ -39,6 +41,7 @@ module Insika
       require "opentelemetry/sdk"
       require "opentelemetry/exporter/otlp"
       load_metrics_sdk
+      OpenTelemetry.logger = sdk_logger
       unless @configured
         OpenTelemetry::SDK.configure { |c| c.service_name = service_name }
         @configured = true
@@ -49,6 +52,13 @@ module Insika
                    meter: meter, pricing: pricing(env))
     end
 
+    # The SDK's default logger writes to $stdout, which Ruby buffers when it is a
+    # pipe (Falcon workers, a container log): a rejected export (404 from an
+    # ingest that wants a header) never reached the log. $stderr is unbuffered.
+    def sdk_logger(io = $stderr)
+      Logger.new(io, progname: "otel", level: ENV.fetch("OTEL_LOG_LEVEL", "warn"))
+    end
+
     # Did `setup` wire the metric instruments too (SDK present, at least one reader)?
     # Only meaningful after `setup` — it exists for the boot banners.
     def metrics? = @metrics == true
@@ -68,7 +78,7 @@ module Insika
     # Operator-declared rates (USD per million tokens) as JSON in
     # INSIKA_MODEL_PRICING. Unset/malformed -> an empty table -> no cost is reported.
     def pricing(env = ENV)
-      table = Pricing.parse(Insika::EnvSchema.read("INSIKA_MODEL_PRICING", env))
+      table = Pricing.from_env(env)
       table.empty? ? nil : table
     end
 

data/lib/insika/templates/daily-digest/README.md

@@ -20,6 +20,19 @@ Then open `/studio`, log in with the printed token, and either wait for the
 schedule (22:00 America/Sao_Paulo) or send a message to the "reporter" agent
 in the Playground — the artifact lands on the Artifacts tab either way.
 
+## Report design
+
+The skill asks for a dated executive takeaway, consistent KPI cards, warm neutrals
+with one amber accent, labeled charts, sources and limitations. Reports adapt to
+phone widths and the system light/dark preference. Native Chart/Table radio choices,
+CSS hover/focus highlights and expandable details work without JavaScript. Exact
+values remain accessible on touch and in a table; focus is visible, 140ms transitions
+respect reduced motion, and print includes the full table and details.
+
+See the [fictional-data example](https://github.com/guizaols/insika/blob/main/examples/scheduled-report/interactive-report.html).
+These interactions explore a saved snapshot, not live data. This guidance applies
+to newly generated reports; existing artifacts stay unchanged.
+
 ## What's real here
 
 - The **schedule** is a live engine feature: the tick actually fires this

data/lib/insika/templates/daily-digest/agent.rb

@@ -47,21 +47,32 @@ reporter = Insika.agent("reporter") do
            overrides: { turn_timeout: 600, max_tool_calls: 120 }
 
   # The generic, store-free skill: how a report is BUILT — the inline-SVG
-  # pattern (palette, table, pure-SVG bars, light/dark). No store ids, no
+  # pattern (palette, table, native controls, light/dark). No store ids, no
   # queries — that half belongs in a merchant's pack, not here.
   skill "daily-digest",
         description: "How to build the daily sales digest as a self-contained HTML report",
         instructions: <<~MD
-          Build the digest as ONE self-contained HTML page:
-          - a <style> block with a light palette (e.g. #f8fafc bg, #0f172a text,
-            #6366f1 accent), plus a prefers-color-scheme: dark override;
-          - one <table> of the numbers (th/tbody, right-aligned amounts);
-          - one inline SVG bar chart (no <script>, no <img>, no <iframe>,
-            no external fonts or fetches — the report is served with
-            default-src 'none', so nothing external can load);
-          - a title and the run date.
-          Keep it readable on a phone. The report is the deliverable; the
-          channel message is just the link to it.
+          Build ONE self-contained executive HTML report with a <style> block:
+          - Lead with a clear title, period, generation date and concise,
+            evidence-backed takeaway. Name sources and limitations. Use only
+            supplied numbers; show missing data honestly and label demo data.
+          - Use warm neutrals and one amber accent (or the merchant's accent),
+            consistent type, spacing and KPI cards, and system dark mode.
+          - Include a responsive inline SVG or HTML bar chart with clear labels,
+            units and exact values, plus a captioned table with column headers.
+          - Offer Chart/Table through labeled, focusable native radios grouped
+            in a fieldset with a legend; use CSS :checked, not ARIA tabs.
+          - Use hover/focus tooltips in reserved space; keep them visible when
+            hovered. Add CSS highlights, a visible 2px focus outline, and
+            details/summary for supporting evidence. Exact values
+            must remain available on touch without hovering.
+          - Use 140ms color/opacity transitions; disable them for reduced motion.
+            No decorative animation. Print the full table and supporting details
+            regardless of the selected view or collapsed state; hide controls.
+          - This is a dated data snapshot, not a live feed. No scripts, event
+            handlers, forms, iframe, external fonts or fetches. The report's
+            default-src 'none' policy blocks external resources.
+          Keep it readable on a phone. The channel message is just the link.
         MD
 end
 

data/lib/insika/testing/store_contract.rb

@@ -117,6 +117,12 @@ RSpec.shared_examples "an Insika store" do
       expect(store.list("s", "task:")).to eq(%w[task:1 task:2])
     end
 
+    it "keeps the prefix boundary exact, ASCII or not" do
+      %w[task task: task:1 task:é task; tasks sessão:1 sessão:2 sessãoX run9 run9a run: taz taz1 ta{].each { |k| store.set("s", k, 1) }
+      expect([store.list("s", "task:"), store.list("s", "sessão:"), store.list("s", "run9"), store.list("s", "taz")])
+        .to eq([%w[task: task:1 task:é], %w[sessão:1 sessão:2], %w[run9 run9a], %w[taz taz1]])
+    end
+
     it " returns [] for an empty scope" do #
       expect(store.list("s")).to eq([])
     end
@@ -128,6 +134,65 @@ RSpec.shared_examples "an Insika store" do
     end
   end
 
+  # Bulk read: what a caller that lists keys and reads each one needs, in one
+  # call. A backend may answer it in one query; the default is list + get.
+  describe "#entries" do
+    it "returns [key, value] pairs sorted by key, values deserialized" do
+      store.set("s", "b", { "n" => 2 })
+      store.set("s", "a", [1])
+      store.set("other", "a", "x")
+      expect(store.entries("s")).to eq([["a", [1]], ["b", { "n" => 2 }]])
+    end
+
+    it "filters by prefix with start_with?, ASCII or not" do
+      store.set("s", "ab", 1)
+      store.set("s", "abc", 2)
+      store.set("s", "b", 3)
+      store.set("s", "é1", 4)
+      expect(store.entries("s", "ab")).to eq([["ab", 1], ["abc", 2]])
+      expect(store.entries("s", "é")).to eq([["é1", 4]])
+    end
+
+    it "returns [] for an empty scope" do
+      expect(store.entries("nothing")).to eq([])
+    end
+  end
+
+  # The last-written keys, newest first: what a "recent" list needs without
+  # reading the whole scope.
+  describe "#recent" do
+    it "returns the most recently written pairs first, capped at limit" do
+      store.set("s", "a", { "n" => 1 })
+      store.set("s", "b", { "n" => 2 })
+      store.set("s", "c", { "n" => 3 })
+      store.set("s", "a", { "n" => 4 }) # rewritten: now the newest
+      expect(store.recent("s", nil, 2)).to eq([["a", { "n" => 4 }], ["c", { "n" => 3 }]])
+    end
+
+    it "skips the newest `offset` pairs (the next page)" do
+      %w[a b c d e].each_with_index { |k, i| store.set("s", "p:#{k}", i) }
+      expect(store.recent("s", "p:", 2, 0).map(&:first)).to eq(%w[p:e p:d])
+      expect(store.recent("s", "p:", 2, 2).map(&:first)).to eq(%w[p:c p:b])
+      expect(store.recent("s", "p:", 2, 4).map(&:first)).to eq(%w[p:a])
+      expect(store.recent("s", nil, 10, 5)).to eq([])
+    end
+
+    it "an amended key keeps its place; an absent one is written" do
+      store.set("s", "a", { "n" => 1 })
+      store.set("s", "b", { "n" => 2 })
+      store.amend("s", "a", { "n" => 3 })
+      store.amend("s", "c", { "n" => 4 })
+      expect(store.recent("s", nil, 3)).to eq([["c", { "n" => 4 }], ["b", { "n" => 2 }], ["a", { "n" => 3 }]])
+    end
+
+    it "keeps to the scope and the prefix" do
+      store.set("s", "x:1", 1)
+      store.set("other", "x:2", 2)
+      store.set("s", "y:1", 3)
+      expect(store.recent("s", "x:", 10)).to eq([["x:1", 1]])
+    end
+  end
+
   describe "#scopes" do
     it " returns scope names sorted lexicographically" do #
       store.set("zeta", "k", 1)

data/lib/insika/text_tool_call.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  # A tool call the model wrote as TEXT instead of through the API's `tool_calls`.
+  #
+  # deepseek-v4-flash does it now and then: the message comes back with no tool call
+  # and a body like
+  #
+  #   <tool_call>
+  #   search_faq
+  #   <parameter name="query">quem é a loja Exemplo</parameter>
+  #   </tool_call>
+  #
+  # Left alone that is the turn's ANSWER: the tool never runs, the consumer's leak
+  # guard swallows the text and the customer gets silence — and the markup stays in
+  # the session history, where the model reads itself calling tools that way and does
+  # it again (Loja Exemplo, 23/10/2026). The Executor rewrites such a message
+  # into a real tool call before the next step, so the loop runs the tool and the
+  # history holds what a normal call would have left.
+  #
+  # Two spellings: the name-then-<parameter> one above (the one seen in production)
+  # and the Hermes/Qwen JSON one (`<tool_call>{"name": …, "arguments": {…}}`).
+  # Anything else — or a name the chat does not offer — is NOT recovered: inventing a
+  # call is worse than the silence the consumer already guards.
+  module TextToolCall
+    BLOCK = %r{<tool_call>\s*(.*?)\s*</tool_call>}m
+    PARAM = %r{<parameter\s+name\s*=\s*"([^"]+)"\s*>(.*?)</parameter>}m
+    NAME = /\A([A-Za-z_][\w.-]*)\s*(?:<|\z)/
+
+    module_function
+
+    # content: the assistant message text. known: the tool names the chat offers.
+    # -> { calls: [{ name:, arguments: }], text: what is left outside the blocks } | nil
+    def parse(content, known)
+      text = content.to_s
+      return nil unless text.include?("<tool_call>")
+
+      calls = text.scan(BLOCK).map { |(body)| call_from(body) }
+      return nil if calls.empty? || calls.any? { |call| call.nil? || !known.include?(call[:name]) }
+
+      { calls: calls, text: text.gsub(BLOCK, "").strip }
+    end
+
+    def call_from(body)
+      return json_call(body) if body.start_with?("{")
+
+      name = body[NAME, 1] or return nil
+      # ponytail: parameter values stay strings (the spelling carries no types);
+      # every tool seen leaking takes strings. Coerce by schema if one ever doesn't.
+      { name: name, arguments: body.scan(PARAM).to_h { |key, value| [key, value.strip] } }
+    end
+
+    def json_call(body)
+      data = JSON.parse(body)
+      return nil unless data.is_a?(Hash) && data["name"].is_a?(String)
+
+      arguments = data["arguments"]
+      arguments = JSON.parse(arguments) if arguments.is_a?(String)
+      { name: data["name"], arguments: arguments.is_a?(Hash) ? arguments : {} }
+    rescue JSON::ParserError
+      nil
+    end
+  end
+end

data/lib/insika/tick.rb

@@ -34,7 +34,7 @@ module Insika
     def initialize(store:, recovery:, channel_delivery:, logger: nil,
                    interval: DEFAULT_INTERVAL, stale_after: DEFAULT_STALE_AFTER,
                    sleeper: nil, retention: nil, funnel: nil, followup: nil,
-                   schedule: nil)
+                   schedule: nil, model_registry: nil)
       @store = store
       @recovery = recovery
       @channel_delivery = channel_delivery
@@ -46,6 +46,7 @@ module Insika
       @funnel = funnel # the tick-driven outcome fold; nil = none
       @followup = followup # the tick-driven follow-up firer; nil = none
       @schedule = schedule # the recurring-schedule firer; nil = none
+      @model_registry = model_registry # the daily model-catalog refresh; nil = none
     end
 
     # the fold is wired after the Tick is built (the graph passes
@@ -61,6 +62,9 @@ module Insika
     # (same shape — the stores come from the spine).
     attr_accessor :schedule
 
+    # the daily RubyLLM model-catalog refresh (ModelRegistry), same shape.
+    attr_accessor :model_registry
+
     def enabled? = @interval.positive?
 
     # One pass, pure (no reactor needed): the serving loop calls it on a timer,
@@ -85,6 +89,8 @@ module Insika
       # the same claim-window discipline as the follow-up firer.
       schedule_summary = @schedule&.run
       summary[:schedule] = schedule_summary if schedule_summary
+      registry_summary = @model_registry&.run
+      summary[:model_registry] = registry_summary if registry_summary
       return summary unless claim_window
 
       result = @recovery.run(stale_after: @stale_after)

data/lib/insika/token_store.rb

@@ -112,6 +112,10 @@ module Insika
     # NOTHING valid. -> { revoked: n, issue: Issue }.
     def rotate(tenant_id:, label: "default", now: Time.now)
       @store.transaction do
+        # A key no one writes, read first: on a backend that locks per key read,
+        # two rotations of one tenant run one after the other, so the second
+        # revokes the token the first issued.
+        @store.get(SCOPE, "#{ROTATE_PREFIX}#{tenant_id}")
         revoked = revoke_all(tenant_id: tenant_id)
         { revoked: revoked, issue: issue(tenant_id: tenant_id, label: label) }
       end
@@ -145,6 +149,7 @@ module Insika
     end
 
     RECORD_PREFIX = "r:"
+    ROTATE_PREFIX = "rotate:" # never written: only read, to serialize rotations
     HASH_PREFIX = "h:"
 
     def record_key(id) = "#{RECORD_PREFIX}#{id}"

data/lib/insika/tool_batch.rb

@@ -39,7 +39,7 @@ module Insika
     # From after_tool_result, with the RAW result: a Tool::Halt is only
     # recognizable there.
     def halt!(result)
-      @halted = true if defined?(RubyLLM::Tool::Halt) && result.is_a?(RubyLLM::Tool::Halt)
+      @halted = true if defined?(Insika::ToolDefinition::Halt) && result.is_a?(Insika::ToolDefinition::Halt)
     end
 
     def halted? = @halted

data/lib/insika/tool_catalog.rb

@@ -14,13 +14,20 @@ module Insika
   # no instantiation at all; a broken factory surfaces on first use (where the
   # Executor would also catch it at stage 3), not at construction.
   class ToolCatalog
-    Entry = Data.define(:name, :description)
+    Entry = Data.define(:name, :description, :plugin) do
+      def initialize(name:, description:, plugin: nil)
+        super
+      end
+    end
 
     def initialize(tool_registry:)
       @tool_registry = tool_registry
     end
 
     def all
+      gen = registry_generation
+      @entries = nil if gen != @generation
+      @generation = gen
       @entries ||= build_entries
     end
 
@@ -29,6 +36,7 @@ module Insika
     # restart. An in-flight turn has already captured `all`.
     def reload
       @entries = build_entries
+      @generation = registry_generation
       self
     end
 
@@ -76,7 +84,7 @@ module Insika
 
     def build_entries
       @tool_registry.entries.map do |entry|
-        Entry.new(name: entry.name, description: entry.factory.call.description.to_s)
+        Entry.new(name: entry.name, description: entry.factory.call.description.to_s, plugin: entry.plugin)
       end
     end
 
@@ -85,5 +93,7 @@ module Insika
       desc = entry.description.downcase
       terms.sum { |term| (name.include?(term) ? 2 : 0) + (desc.include?(term) ? 1 : 0) }
     end
+
+    def registry_generation = @tool_registry.respond_to?(:generation) ? @tool_registry.generation : nil
   end
 end

data/lib/insika/tool_definition.rb

@@ -20,7 +20,7 @@ module Insika
   #     "group" => string|nil, "tags" => ["b2b",...] }  #//
   #
   # `parameters` is **JSON Schema** (the interlingua of OpenAI/Anthropic/MCP):
-  # a nestable object, fed straight into RubyLLM's `params_schema` (provider-
+  # a nestable object, fed straight into RubyLLM's `parameters_schema` (provider-
   # agnostic). The **flat array** (`[{name,type,required}]`) is SUGAR for the simple
   # case: it is lifted to JSON Schema at build time. The sugar covers scalars and
   # `array:<scalar>` — it CANNOT express an array of objects, and says so instead of
@@ -41,6 +41,11 @@ module Insika
   )
 
   class ToolDefinition
+    # Terminal tool results finish the current batch without another model request.
+    Halt = Data.define(:content) do
+      def to_s = content.to_s
+    end
+
     # Flat-sugar types: the SCALARS, plus `array:<scalar>` for a list. There is no bare
     # `array`: an array without an item type is an INCOMPLETE declaration, and the
     # engine refuses to guess one (see lift_flat_params).
@@ -163,6 +168,8 @@ module Insika
 
     def presentation? = !presentation.nil?
 
+    # Public because an MCP tool has the same question to answer and there must be
+    # one reading of "these parameters may only carry an id some tool returned".
     def self.normalize_requires_evidence(value, param_names)
       return nil if value.nil?
 
@@ -173,7 +180,6 @@ module Insika
 
       { "params" => params.map(&:to_s).uniq }
     end
-    private_class_method :normalize_requires_evidence
 
     # Group: enablement label by DATA (not name convention),
     # target of AgentProfile's `tools_allow_groups`. Trimmed; empty/nil -> nil.
@@ -542,7 +548,7 @@ module Insika
       nil
     end
 
-    # HOW `say` REACHES THE EXECUTOR. RubyLLM's `Tool::Halt` carries one value, and
+    # HOW `say` REACHES THE EXECUTOR. Insika::ToolDefinition::Halt carries one value, and
     # that value is the tool's payload (the trace records it, and the model never
     # sees it — the halt ends the loop). So a halt that has something to publish
     # carries BOTH, under keys distinctive enough that a trace reader knows what
@@ -576,7 +582,7 @@ module Insika
 
     # FLAT view of the top-level properties (name/type/description/required) — for
     # RubyLLM's `#parameters` (discovery/tool_search) and the simple authoring UI.
-    # The full nested schema goes through `params_schema` (DataDefinedTool). Symbol-
+    # The full nested schema goes through `parameters_schema` (DataDefinedTool). Symbol-
     # keyed for compat with callers that already consumed the flat params.
     def top_level_params
       props = parameters["properties"] || {}