insika 0.8.0 → 1.0.1

data/lib/insika/tool_usage_report.rb

@@ -72,7 +72,7 @@ module Insika
         stats = tool_stats(sessions[id] || [], cutoff)
         never_called_rows(id, record, stats) +
           error_rate_rows(id, stats, days) +
-          stale_rows(id, stats)
+          stale_rows(id, stats) + blocked_rows(id, stats, days)
       end
 
       Report.new(generated_at: now.iso8601, days: days,
@@ -87,8 +87,8 @@ module Insika
     # workflows without a chat) contributes nothing.
     def sessions_by_agent
       acc = Hash.new { |h, k| h[k] = [] }
-      @task_store.each_id do |task_id|
-        task = @task_store.find(task_id) or next
+      tasks = @task_store.respond_to?(:all) ? @task_store.all : @task_store.each_id.filter_map { |id| @task_store.find(id) }
+      tasks.each do |task|
         agent = task.command.is_a?(Hash) ? task.command.dig("payload", "agent") : nil
         next if agent.to_s.empty? || task.session_id.to_s.empty?
 
@@ -100,7 +100,7 @@ module Insika
     # tool name -> { calls:, errors:, window_calls:, window_errors:, last_at: }
     # over every stored trace entry of the agent's sessions.
     def tool_stats(session_ids, cutoff)
-      stats = Hash.new { |h, k| h[k] = { calls: 0, errors: 0, window_calls: 0, window_errors: 0, last_at: nil } }
+      stats = Hash.new { |h, k| h[k] = { calls: 0, errors: 0, window_calls: 0, window_errors: 0, blocked: Hash.new(0), last_at: nil } }
       session_ids.each do |sid|
         @tool_trace_store.for_session(sid).each do |entry|
           s = stats[entry["tool"].to_s]
@@ -113,6 +113,7 @@ module Insika
 
           s[:window_calls] += 1
           s[:window_errors] += 1 if error
+          s[:blocked][entry["gate"]] += 1 if entry["gate"]
         end
       end
       stats
@@ -142,6 +143,15 @@ module Insika
       end
     end
 
+    def blocked_rows(agent, stats, days)
+      stats.flat_map do |tool, s|
+        s[:blocked].map do |gate, count|
+          Row.new(agent: agent, tool: tool, kind: "blocked",
+                  detail: "#{count} call(s) blocked by #{gate} in the last #{days} day(s)")
+        end
+      end
+    end
+
     def stale_rows(agent, stats)
       stats.filter_map do |tool, s|
         next if s[:window_calls].positive? || s[:last_at].nil?

data/lib/insika/tools/a2a_remote.rb

@@ -9,7 +9,7 @@ module Insika
     # enter lib/insika.rb; it is loaded in the registration block (wiring) on the 1st
     # instance. One instance per remote agent (its own name/description).
     class A2ARemote < RubyLLM::Tool
-      param :message, desc: "The message/task for the remote agent"
+      parameter :message, description: "The message/task for the remote agent"
 
       def initialize(client:, url:, tool_name:, description:, event_stream: nil)
         @client = client

data/lib/insika/tools/agent_enum.rb

@@ -11,7 +11,7 @@ module Insika
     # the provider sees.
     #
     # Tolerant by construction: JSON-schema hashes reach us with symbol keys (the
-    # class-level `params(...)` form) or string keys (anything that round-tripped
+    # class-level `parameters(...)` form) or string keys (anything that round-tripped
     # through JSON), and a shape we do not recognize is returned UNTOUCHED — a
     # schema we failed to annotate still works, one we corrupted would break every
     # delegation.

data/lib/insika/tools/confirm_pending.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # What the two confirmation tools share: finding the customer's hold and
+    # refusing anyone else's — another conversation's, the operator's, or one
+    # already decided. Errors go back to the MODEL as bodies, never as
+    # exceptions: a tool exception never ends the turn.
+    module Confirmation
+      CUSTOMER = PendingActionStore::CUSTOMER
+
+      module_function
+
+      # -> [PendingAction, nil] | [nil, String]
+      def open_hold(state, pending_id)
+        store = state.pending_action_store
+        pending = store&.find(pending_id.to_s)
+        return [nil, "no held action with pending_id #{pending_id}"] if pending.nil?
+        return [nil, "#{pending_id} is not a customer confirmation"] unless pending.kind == CUSTOMER
+        return [nil, "#{pending_id} belongs to another conversation"] unless pending.session_id.to_s == state.task.session_id.to_s
+        # The hold and the answer to it are two customer messages, which is two
+        # TASKS. A hold THIS task created has not been put to the customer yet —
+        # the reply carrying it has not even been sent. Deciding it here would be
+        # the model confirming itself, and the write would land with nobody's word
+        # behind it.
+        return [nil, "#{pending_id} was held on this same turn; the customer has not answered it yet"] if pending.task_id.to_s == state.task.id.to_s
+        return [nil, "#{pending_id} was already #{pending.status}"] unless pending.status == :pending
+
+        [pending, nil]
+      end
+
+      # The turn's enveloped instance of the held tool — the same wrapper the
+      # hold came from, so the confirmed run pays every check but the hold.
+      def held_tool(state, name)
+        Array(state.allowed_tools).find do |tool|
+          tool.respond_to?(:call_confirmed) &&
+            (tool.name.to_s == name || (tool.respond_to?(:impl_name) && tool.impl_name.to_s == name))
+        end
+      end
+
+      def emit(event_stream, state, type, pending)
+        event_stream&.emit(Insika::Event.new(
+                             type: type,
+                             data: { pending_id: pending.id, tool: pending.tool },
+                             meta: { task_id: state.task.id, session_id: state.task.session_id }
+                           ))
+      end
+    end
+
+    # Runs an action the engine held for the customer's confirmation. The
+    # decision is written FIRST (durable — a crash between the two re-executes
+    # the turn and finds it approved), the original tool runs SECOND through its
+    # own envelope with the arguments recorded at the hold: there is no path to
+    # confirm different arguments than the ones the customer was shown.
+    # System builtin (like remember): `require "ruby_llm"` stays in THIS file,
+    # loaded lazily by the Executor in create_chat.
+    class ConfirmPending < RubyLLM::Tool
+      description "Runs an action the customer has just confirmed. Call it only when the customer's " \
+                  "message agrees to exactly what was proposed; a change, a question or a new request " \
+                  "is cancel_pending instead."
+      parameter :pending_id, description: "The pending_id the held action returned"
+
+      def name = "confirm_pending"
+
+      def initialize(event_stream:, state:)
+        @event_stream = event_stream
+        @state = state
+        super()
+      end
+
+      def execute(pending_id:)
+        pending, error = Confirmation.open_hold(@state, pending_id)
+        return { error: error } if error
+
+        tool = Confirmation.held_tool(@state, pending.tool)
+        return { error: "#{pending.tool} is not available on this turn" } unless tool
+
+        @state.pending_action_store.resolve(pending.id, decision: :approved, operator: Confirmation::CUSTOMER)
+        Confirmation.emit(@event_stream, @state, :confirmation_confirmed, pending)
+        tool.call_confirmed(pending.args || {})
+      end
+    end
+
+    # Drops a held action: the customer declined, changed something, or asked
+    # for anything else. The hold would expire on its own at the end of this
+    # turn; cancelling says so now, and lets the model answer accordingly.
+    class CancelPending < RubyLLM::Tool
+      description "Drops an action that was waiting for the customer's confirmation, because they " \
+                  "declined, changed something, or asked for something else."
+      parameter :pending_id, description: "The pending_id the held action returned"
+
+      def name = "cancel_pending"
+
+      def initialize(event_stream:, state:)
+        @event_stream = event_stream
+        @state = state
+        super()
+      end
+
+      def execute(pending_id:)
+        pending, error = Confirmation.open_hold(@state, pending_id)
+        return { error: error } if error
+
+        @state.pending_action_store.resolve(pending.id, decision: :rejected, operator: Confirmation::CUSTOMER)
+        Confirmation.emit(@event_stream, @state, :confirmation_cancelled, pending)
+        { "status" => "cancelled", "tool" => pending.tool }
+      end
+    end
+  end
+end

data/lib/insika/tools/data_defined_tool.rb

@@ -12,7 +12,7 @@ module Insika
     # it is NOT required in lib/insika.rb; the overlay loads it lazily at registration
     #
     # Contract preserved by duck-typing: it overrides name/description/parameters/
-    # execute; RubyLLM's params_schema derives from #parameters automatically.
+    # execute; RubyLLM's parameters_schema derives from #parameters automatically.
     # execute NEVER raises — an error (missing param, blocked egress, HTTP, parse)
     # becomes `{ error: }` to the model, like the other tools.
     class DataDefinedTool < RubyLLM::Tool
@@ -47,21 +47,13 @@ module Insika
       # envelope's duck-typed resolution checks this FIRST — a data-tool declares
       # its evidence on its definition, never in the registry metadata.
       def evidence = @definition.evidence
+      def requires_evidence = @definition.requires_evidence
 
-      # FULL (nested) JSON Schema straight into RubyLLM's params_schema — it is what
+      # FULL (nested) JSON Schema straight into RubyLLM's parameters_schema — it is what
       # the providers serialize (OpenAI/Anthropic/Gemini/Bedrock prefer
-      # params_schema; parameters is just a fallback). Provider-agnostic and
+      # parameters_schema; parameters is just a fallback). Provider-agnostic and
       # the only form that expresses nesting (object/array/enum).,.
-      def params_schema = @definition.parameters
-
-      # FLAT top-level view for discovery (tool_search calls #parameters on the resolved
-      # tool). The real nested schema goes through #params_schema above.
-      def parameters
-        @parameters ||= @definition.top_level_params.each_with_object({}) do |p, acc|
-          sym = p[:name].to_sym
-          acc[sym] = RubyLLM::Parameter.new(sym, type: p[:type], desc: p[:description], required: p[:required])
-        end
-      end
+      def parameters_schema = @definition.parameters
 
       # The args are checked against the tool's own JSON Schema BEFORE the request is
       # built: a call the schema does not allow becomes `{ error: }` the model can act
@@ -71,16 +63,19 @@ module Insika
           return { error: bad }
         end
 
+        t0 = monotonic
         req = build_request(kwargs)
         reason = @egress.violation(req[:url], **@egress_options)
         return { error: "destination blocked: #{reason}" } if reason
 
+        t1 = monotonic
         result = @http.request(**req)
+        record_timing(t0, t1, result)
         emit(result[:status])
         payload = extract(result)
         # The RESPONSE says the turn is over (`halt_when`): the backend already
         # answered the customer, so letting the model comment would deliver the
-        # message twice. RubyLLM's Tool::Halt ends its loop right here — no second
+        # message twice. Insika::ToolDefinition::Halt ends its loop right here — no second
         # provider call, and the decision is the engine's, not a request in a prompt.
         # Only on a 2xx: an error body that happens to carry the value is a failure,
         # and a failure must reach the model.
@@ -89,7 +84,7 @@ module Insika
           # the model wrote no lead-in. Wrapped only when there is one, so every tool
           # that declares no `say` keeps producing exactly the payload it always did.
           say = @definition.halt_say(result[:body])
-          return RubyLLM::Tool::Halt.new(say ? Insika::ToolDefinition.wrap_halt(payload, say) : payload)
+          return Insika::ToolDefinition::Halt.new(say ? Insika::ToolDefinition.wrap_halt(payload, say) : payload)
         end
 
         payload
@@ -219,6 +214,20 @@ module Insika
 
       # No task correlation (registry tool does not receive TurnState) -> meta {}.
       # Emits only name + status: NEVER body/headers (0 secret leakage, R2).
+      def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      # Where the call's time went, for the ToolEnvelope's trace (same fiber): the
+      # request build + egress check, the HTTP round trip as this process saw it, and
+      # the server's own runtime when it reports one. A wide gap between http_ms and
+      # server_ms is network or this process being slow to resume the call.
+      def record_timing(t0, t1, result)
+        Thread.current[Insika::ToolEnvelope::TIMING_KEY] = {
+          "pre_ms" => ((t1 - t0) * 1000).round,
+          "http_ms" => ((monotonic - t1) * 1000).round,
+          "server_ms" => result[:server_ms]
+        }.compact
+      end
+
       def emit(status)
         @event_stream&.emit(Insika::Event.new(
                               type: :data_tool_call, data: { tool: @definition.name, status: status }, meta: {}

data/lib/insika/tools/generate_image.rb

@@ -27,9 +27,9 @@ module Insika
                   "prompt alone — UNLESS this turn carries an inbound photo, in which case " \
                   "that photo is edited by default (pass source_image_urls explicitly to " \
                   "generate from scratch instead)."
-      # explicit JSON-schema form (the `param` DSL only reaches strings/scalars,
+      # explicit JSON-schema form (the `parameter` DSL only reaches strings/scalars,
       # and source_image_urls needs a typed array — the bare-array gotcha, #128).
-      params(
+      parameters(
         type: "object",
         properties: {
           prompt: { type: "string", description: "What to draw, or what edit to make, in detail" },

data/lib/insika/tools/load_knowledge.rb

@@ -16,7 +16,7 @@ module Insika
     # loads it lazily inside create_chat, same as load_skill.
     class LoadKnowledge < RubyLLM::Tool
       description "Loads the complete content of a learned concept by name"
-      param :name, desc: "Exact concept name, as listed in <knowledge>"
+      parameter :name, description: "Exact concept name, as listed in <knowledge>"
 
       # RubyLLM::Tool#name derives from self.class.name — for a nested class it
       # produces "insika--tools--load_knowledge", not "load_knowledge" (which
@@ -47,7 +47,11 @@ module Insika
       private
 
       def load(name)
-        content = @store.get(@agent_id, name.to_s, tenant: @tenant)
+        content = if @state&.respond_to?(:shared_conversations) && @state.shared_conversations
+          @state.shared_conversations.memory_get(task:@state.task,id:name.to_s,kind:'knowledge')&.fetch('value')
+        else
+          @store.get(@agent_id, name.to_s, tenant: @tenant)
+        end
         return { error: "concept '#{name}' not found" } unless content
 
         content
@@ -61,7 +65,7 @@ module Insika
 
         @trace_recorder.record(
           session_id: @state.task.session_id,
-          entry: { "turn" => @state.turn, "tool" => "load_knowledge", "call_id" => "",
+          entry: { "task_id" => @state.task.id.to_s, "turn" => @state.turn, "tool" => "load_knowledge", "call_id" => "",
                    "args" => { "name" => name.to_s }, "result" => result,
                    "ms" => ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round,
                    "at" => Time.now.utc.iso8601 }

data/lib/insika/tools/load_skill.rb

@@ -14,13 +14,13 @@ module Insika
     # loads it lazily inside create_chat.
     class LoadSkill < RubyLLM::Tool
       description "Loads the complete instructions (SKILL.md) of a skill by name"
-      param :name, desc: "Exact skill name, as listed in <available_skills>"
+      parameter :name, description: "Exact skill name, as listed in <available_skills>"
 
       # RubyLLM::Tool#name derives from self.class.name — for a nested class it produces
       # "insika--tools--load_skill", not "load_skill" (which wire_callbacks/
       # :skill_activated and SkillCatalog#format_for_prompt assume). Explicit
       # override. Coexists with
-      # `param :name` (verified: the param is still present).
+      # `parameter :name` (verified: the param is still present).
       def name = "load_skill"
 
       # trace_recorder/state are OPTIONAL (nil = no trace, parity): this tool is
@@ -86,7 +86,7 @@ module Insika
 
         @trace_recorder.record(
           session_id: @state.task.session_id,
-          entry: { "turn" => @state.turn, "tool" => "load_skill", "call_id" => "",
+          entry: { "task_id" => @state.task.id.to_s, "turn" => @state.turn, "tool" => "load_skill", "call_id" => "",
                    "args" => { "name" => name.to_s }, "result" => result,
                    "ms" => ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round,
                    "at" => Time.now.utc.iso8601 }

data/lib/insika/tools/present.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # PRESENTATION tool: the model says WHICH products to show, the engine decides
+    # WHAT is shown. Built by the overlay registry from a ToolDefinition that
+    # declares `presentation` (one class, N instances — like DataDefinedTool).
+    #
+    # Cards used to be a side effect of evidence: every attachment a search tool
+    # returned rode the channel delivery, all of them, and the model had no way to
+    # say "these three, not the ten I searched". The deployments compensated with
+    # inline markers in the text, parsed by regex on their side — where most of
+    # the hallucinated ids came from. Here text never carries product data: the
+    # model picks ids, and the engine
+    #   1. keeps only ids the session's evidence ledger has seen (provenance),
+    #   2. joins each to the card the evidence tool already hoarded this turn,
+    #   3. caps at the declared `max`,
+    #   4. records the selection on the turn (the delivery sends THAT),
+    #   5. emits `:ui` on the stream (the edge publishes it as `insika.ui`),
+    #   6. tells the model what was shown and what was dropped, and why.
+    # No HTTP, no model call, deterministic. `execute` never raises.
+    class Present < RubyLLM::Tool
+      # The one sentence for the model when NOTHING could be shown. Engine-generic:
+      # the pack tunes vocabulary through the tool's `description`.
+      NOTHING_SHOWN = "no card could be shown; name the products in text or search again"
+
+      def initialize(definition:, event_stream: nil)
+        @definition = definition
+        @event_stream = event_stream
+        @state = nil
+        super()
+      end
+
+      # Deposited by ToolAssembly before the envelope wraps the instance — the
+      # ledger and the hoarded cards live on the turn, never on the registry.
+      def turn_state=(state)
+        @state = state
+      end
+
+      def name = @definition.name
+      def description = @definition.description
+      def parameters_schema = @definition.parameters
+
+      def execute(**kwargs)
+        spec = @definition.presentation
+        ids = Array(kwargs[spec[:ids].to_sym]).map(&:to_s).reject(&:empty?).uniq
+        title = Coercion.presence(kwargs[:title])
+
+        shown, dropped = select(ids, spec[:max])
+        record(spec[:component], title, shown)
+        emit(spec[:component], title, shown, dropped)
+
+        out = { "shown" => shown.map { |c| c["id"] }, "dropped" => dropped }
+        out["instruction"] = NOTHING_SHOWN if shown.empty?
+        out
+      rescue StandardError => e
+        { error: "presentation failed: #{e.message}" }
+      end
+
+      private
+
+      # -> [shown cards, dropped [{id, reason}]]. Order preserved. Reasons:
+      #   unknown — the ledger never saw the id (the model made it up, or the
+      #             customer typed it); no ledger on the state reads as unknown too —
+      #             a check that cannot verify does not pass.
+      #   no_card — the id is known but no evidence tool returned a card for it
+      #             this session (a text-only search result, or a seed of ids alone).
+      #   max     — beyond the declared cap.
+      # Cards come from this turn first, then from the ledger (the last few
+      # searches of the session) — "show me the second one" a turn later works.
+      def select(ids, max)
+        ledger = @state.respond_to?(:evidence_ledger) ? @state.evidence_ledger : nil
+        known = Array(ledger&.ids)
+        turn_cards = @state.respond_to?(:evidence_attachments) ? Array(@state.evidence_attachments) : []
+        session_cards = ledger.respond_to?(:cards) ? Array(ledger.cards) : []
+        by_id = (turn_cards + session_cards).each_with_object({}) { |c, h| h[c["id"]] ||= c if c["id"] }
+
+        shown = []
+        dropped = []
+        ids.each do |id|
+          if !known.include?(id) then dropped << { "id" => id, "reason" => "unknown" }
+          elsif (card = by_id[id]).nil? then dropped << { "id" => id, "reason" => "no_card" }
+          elsif shown.size >= max then dropped << { "id" => id, "reason" => "max" }
+          else shown << card
+          end
+        end
+        [shown, dropped]
+      end
+
+      def record(component, title, shown)
+        return unless @state.respond_to?(:presentations)
+
+        @state.presentations ||= []
+        @state.presentations << { "component" => component, "title" => title,
+                                  "items" => shown.map { |c| c.slice("id", "type", "url", "caption") } }
+      end
+
+      def emit(component, title, shown, dropped)
+        return unless @event_stream
+
+        task = @state.respond_to?(:task) ? @state.task : nil
+        meta = task ? { task_id: task.id, session_id: task.session_id } : {}
+        @event_stream.emit(Insika::Event.new(
+                             type: :ui,
+                             data: { component: component, title: title,
+                                     items: shown.map { |c| c.slice("id", "type", "url", "caption") },
+                                     count: shown.size, dropped: dropped },
+                             meta: meta
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/tools/remember.rb

@@ -13,8 +13,8 @@ module Insika
       description "Stores information to remember in future conversations. Use `key` " \
                   "for a durable key-value fact (overwrites the previous one); omit " \
                   "`key` for a free-form note."
-      param :value, desc: "The content to remember"
-      param :key, desc: "Fact key (e.g.: 'plan', 'name'); omit for a note", required: false
+      parameter :value, description: "The content to remember"
+      parameter :key, description: "Fact key (e.g.: 'plan', 'name'); omit for a note", required: false
 
       # otherwise RubyLLM derives "insika--tools--remember" from the class name.
       def name = "remember"
@@ -28,6 +28,11 @@ module Insika
       end
 
       def execute(value:, key: nil)
+        if @state.shared_conversations
+          kind = key.to_s.strip.empty? ? 'note' : 'fact'
+          record = @state.shared_conversations.propose_memory(task:@state.task,id:kind == 'note' ? SecureRandom.uuid : key.to_s,value:value.to_s,kind:kind)
+          return {proposed:kind,id:record['id'],revision:record['revision']}
+        end
         if key.to_s.strip.empty?
           note = @store.add_note(tenant: @tenant, text: value.to_s)
           emit("note", note.id)

data/lib/insika/tools/run_persona_eval.rb

@@ -45,7 +45,7 @@ module Insika
                   "its target agent and score the whole conversation with the configured " \
                   "judge panel. Refuses if the target exposes a tool that could write for " \
                   "real."
-      param :case_id, desc: "Id of the persona case to run"
+      parameter :case_id, description: "Id of the persona case to run"
 
       def name = "run_persona_eval"
 
@@ -111,7 +111,7 @@ module Insika
         "#{super} Cases you may run: #{ids.join(', ')}."
       end
 
-      def params_schema
+      def parameters_schema
         Insika::Tools::AgentEnum.inject(super, case_ids, path: %i[case_id])
       end
 
@@ -161,7 +161,7 @@ module Insika
         simulator = Insika::Evals::Simulator.new(transport: transport, ask: persona_ask, safety: safety)
 
         conv = "eval-#{golden.id}-#{SecureRandom.hex(4)}" # a fresh session every run (never reused)
-        run = simulator.run(persona: golden.persona, agent: golden.agent, conv: conv)
+        run = simulator.run(persona: golden.persona, agent: golden.agent, conv: conv, state: golden.state)
         verdict = judge.score_conversation(
           rubric: golden.rubric, transcript: run.transcript, policy: golden.policy,
           min_score: golden.min_score || Insika::Evals::Judge::DEFAULT_MIN_SCORE
@@ -199,6 +199,11 @@ module Insika
           llm: llm_context
         )
         bus = Insika::CommandBus.new
+        # a golden with `state:` seeds through the same bus the turn runs on
+        bus.register(:seed_session, Insika::Commands::SeedSession.new(
+                                       session_store: @graph.session_store, memory_store: @graph.memory_store,
+                                       event_stream: @graph.event_stream
+                                     ))
         bus.register(:send_message, Insika::Commands::SendMessage.new(
                                        profiles: @graph.profiles, session_store: @graph.session_store,
                                        task_store: @graph.task_store, executor: executor,
@@ -314,9 +319,7 @@ module Insika
         return if @budget_ledger.nil? || meter.empty?
 
         tokens = meter.sum do |m|
-          m.input_tokens.to_i + m.output_tokens.to_i +
-            (m.respond_to?(:cached_tokens) ? m.cached_tokens.to_i : 0) +
-            (m.respond_to?(:cache_creation_tokens) ? m.cache_creation_tokens.to_i : 0)
+          m.tokens.input.to_i + m.tokens.output.to_i + m.tokens.cache_read.to_i + m.tokens.cache_write.to_i
         end
         return if tokens.zero?
 

data/lib/insika/tools/save_artifact.rb

@@ -17,11 +17,21 @@ module Insika
     class SaveArtifact < RubyLLM::Tool
       description "Save an HTML (or markdown / SVG) page — a report, a digest, " \
                   "a summary — and get back a URL to share. Use when the answer " \
-                  "is a document the channel message cannot carry."
-      param :title, desc: "Short human-readable title (<= 200 chars)"
-      param :content, desc: "The page content: HTML with inline SVG for charts, " \
-                            "markdown, or SVG. No scripts, no external resources."
-      param :mime, desc: "text/html (default), text/markdown, or image/svg+xml",
+                  "is a document the channel message cannot carry. Executive reports " \
+                  "need a clear title, period, generation date, evidence-backed takeaway, " \
+                  "sources and limitations."
+      parameter :title, description: "Short human-readable title (<= 200 chars)"
+      parameter :content, description: "HTML, markdown, or SVG. HTML reports: use warm neutrals " \
+                            "and one amber or merchant accent, consistent type/spacing/KPI cards, " \
+                            "responsive SVG or HTML charts with labels, units and exact values/table. " \
+                            "Use CSS hover/focus highlights and hoverable tooltips in reserved space, " \
+                            "labeled native radio chart/table " \
+                            "choices and details; keep values accessible on touch and focus " \
+                            "visible. Support system dark mode, print with full tables/details, " \
+                            "and 140ms transitions disabled for reduced motion. Date the data " \
+                            "snapshot; never imply live updates. No scripts, event handlers, " \
+                            "forms, external resources or decorative animation."
+      parameter :mime, description: "text/html (default), text/markdown, or image/svg+xml",
                    required: false
 
       def name = "save_artifact"
@@ -92,4 +102,4 @@ module Insika
       end
     end
   end
-end
+end

data/lib/insika/tools/schedule_followup.rb

@@ -20,8 +20,8 @@ module Insika
                   "when the customer agrees to be contacted again (a product, a " \
                   "cart, a pending payment). The cancellation policy is permanent: " \
                   "a customer who opted out can never be rescheduled."
-      param :at, desc: "ISO 8601 (absolute) or relative '+6h' / '+2d'"
-      param :reason, desc: "Short machine-readable reason, e.g. 'pix pending, " \
+      parameter :at, description: "ISO 8601 (absolute) or relative '+6h' / '+2d'"
+      parameter :reason, description: "Short machine-readable reason, e.g. 'pix pending, " \
                            "customer said she would pay tonight'"
 
       def name = "schedule"
@@ -127,7 +127,7 @@ module Insika
     class CancelFollowup < RubyLLM::Tool
       description "Cancel a previously scheduled follow-up by its id. A follow-up " \
                   "that already fired cannot be cancelled."
-      param :id, desc: "The id returned by the schedule tool"
+      parameter :id, description: "The id returned by the schedule tool"
 
       def name = "cancel_followup"
 

data/lib/insika/tools/stuck_signal.rb

@@ -19,8 +19,8 @@ module Insika
       description "Signal that you cannot proceed and end the turn. Use when the " \
                   "request is out of your scope, you lack the data to help, or a human " \
                   "must take over. Write your final sentence to the customer first."
-      param :reason, desc: "Why you cannot proceed (goes to the operator, not the customer)"
-      param :message, desc: "Optional final message if you wrote none", required: false
+      parameter :reason, description: "Why you cannot proceed (goes to the operator, not the customer)"
+      parameter :message, description: "Optional final message if you wrote none", required: false
 
       def name = "signal_stuck"
 
@@ -34,7 +34,7 @@ module Insika
         # A Halt ends the tool loop here, so the turn cannot continue after declaring
         # stuck. The payload's `say` is the fallback final message when the model
         # wrote no lead-in (the executor's halt_answer already prefers the lead-in).
-        RubyLLM::Tool::Halt.new(Insika::ToolDefinition.wrap_halt(
+        Insika::ToolDefinition::Halt.new(Insika::ToolDefinition.wrap_halt(
                                   { "reason" => reason.to_s },
                                   message.to_s
                                 ))

data/lib/insika/tools/subagent.rb

@@ -24,10 +24,10 @@ module Insika
                   "it BLOCKS and returns the child's final answer. Set async:true to " \
                   "fire-and-forget a long task: it returns immediately and the child's " \
                   "result arrives later as a new message on this conversation."
-      param :agent, desc: "Id of the child agent to delegate to (must be one this agent may spawn)"
-      param :message, desc: "The self-contained task/prompt for the child agent"
-      param :async, type: :boolean, required: false,
-                    desc: "true = dispatch and continue (result delivered later); default false = wait for the answer"
+      parameter :agent, description: "Id of the child agent to delegate to (must be one this agent may spawn)"
+      parameter :message, description: "The self-contained task/prompt for the child agent"
+      parameter :async, type: :boolean, required: false,
+                    description: "true = dispatch and continue (result delivered later); default false = wait for the answer"
 
       # otherwise RubyLLM derives "insika--tools--subagent" from the class name.
       def name = "spawn_subagent"
@@ -51,7 +51,7 @@ module Insika
         "#{super} Agents you may spawn: #{@allowed.join(', ')}."
       end
 
-      def params_schema
+      def parameters_schema
         @agent_enum_schema ||= Insika::Tools::AgentEnum.inject(super, @allowed, path: %i[agent])
       end
 

data/lib/insika/tools/subagents.rb

@@ -20,9 +20,9 @@ module Insika
                   "subtasks whose results you'll combine: it runs them concurrently " \
                   "(much faster). Each child runs in an ISOLATED context, so put " \
                   "everything it needs in its `message`."
-      # array-of-objects param via the explicit JSON-schema form (the `param` DSL
+      # array-of-objects param via the explicit JSON-schema form (the `parameter` DSL
       # only reaches strings/scalars). Top-level `tasks` arrives as a kwarg to execute.
-      params(
+      parameters(
         type: "object",
         properties: {
           tasks: {
@@ -60,7 +60,7 @@ module Insika
         "#{super} Agents you may spawn: #{@allowed.join(', ')}."
       end
 
-      def params_schema
+      def parameters_schema
         @agent_enum_schema ||= Insika::Tools::AgentEnum.inject(super, @allowed, path: %i[tasks agent])
       end