insika 0.9.0 → 1.0.1

data/lib/insika/tool_envelope.rb

@@ -9,13 +9,29 @@ module Insika
   # + recording of a non-idempotent side-effect BEFORE the result returns to the
   # model. Delegates everything else (name/description/params) to the real tool.
   #
-  # The tool loop belongs to RubyLLM; this is a decorator over the instances —
-  # the Executor never drives roundtrips.
+  # RubyLLM executes tools; this decorator enforces Insika's per-call policy.
   class ToolEnvelope < SimpleDelegator
+    # Fiber-local slot where a tool leaves its timing breakdown for this call's trace.
+    TIMING_KEY = :insika_tool_timing
+
     PROVENANCE_INSTRUCTION = "This value was not returned by any tool in this conversation. " \
                              "Find it with a tool that returns it — a search or a lookup by id — " \
                              "then call this tool again with an id from that result."
 
+    # The words the model reads when a call is held. They are the only thing
+    # standing between a correct store and a customer who was told the opposite:
+    # the engine can refuse the write, it cannot refuse the sentence. Measured —
+    # one reply in twenty announced a held purchase as closed — so the reply's
+    # SHAPE is stated before anything else, and the lie is named concretely
+    # rather than as "do not say it happened".
+    CONFIRMATION_INSTRUCTION = "NOT DONE — nothing was written, and nothing will be until the customer " \
+                               "answers this very message. Your reply must ASK: say exactly what will " \
+                               "happen, with these arguments, and end with the question. A reply that " \
+                               "reports it as finished — 'done', 'closed', 'created', any past tense — is " \
+                               "false, and the customer will act on it. On their next message: if they " \
+                               "confirm, call confirm_pending with this pending_id; if they decline, " \
+                               "change anything, or ask for something else, call cancel_pending."
+
     # The tool timeout's OWN class: distinct from Async::TimeoutError so that
     # the rescue below NEVER swallows the TURN timeout (which uses the default of
     # with_timeout). Without this, a turn overflowing while the fiber is inside a
@@ -24,6 +40,11 @@ module Insika
     ToolTimeout = Class.new(StandardError)
     private_constant :ToolTimeout
 
+    # RubyLLM asks the tool's CLASS whether to defer its definition (tool
+    # search), and a delegator's class is this one. No Insika tool defers, so
+    # every envelope is sent as an ordinary tool.
+    def self.deferred? = false
+
     # A gate's refusal. A plain Hash subclass: it reaches the model exactly as the
     # `{status:, gate:, ...}` it always was, and the engine's own readers (the
     # :tool_result outcome, the trace) recognize a refusal by CLASS — a data tool
@@ -31,6 +52,11 @@ module Insika
     # not one, whatever keys it happens to use.
     class Blocked < Hash; end
 
+    # A call held for the customer's confirmation. Same Hash-subclass trick as
+    # Blocked, and a different class on purpose: nothing was refused and nothing
+    # ran — the next customer message decides, through confirm_pending.
+    class Held < Hash; end
+
     def initialize(tool, state:, checkpoint_store:, tool_registry:, timeout:,
                    skip_side_effects: [], trace_recorder: nil, event_stream: nil)
       super(tool)
@@ -39,19 +65,51 @@ module Insika
       @tool_registry = tool_registry
       @timeout = timeout
       @event_stream = event_stream
-      @skip_side_effects = Array(skip_side_effects) # ids already completed in the interrupted turn
+      @skip_side_effects = Array(skip_side_effects).dup # ids already completed in the interrupted turn
       @trace_recorder = trace_recorder # duck-type: #record(session_id:, entry:). nil = no trace.
     end
 
     # Entry point that RubyLLM invokes (Tool#call in the pinned version).
     # A timeout overflow returns to the MODEL as a serialized error — it does
     # not bring down the turn.
-    def call(args)
+    def call(args = {}, tool_call: nil, **kwargs)
+      @state.current_tool_call = tool_call if tool_call
+      run(args.merge(kwargs), hold: true, native_call: tool_call && native_approvals?)
+    end
+
+    def requires_approval? = native_approvals? && approval_required?
+
+    def approval_tool_name = real_name
+
+    # RubyLLM queries this while inspecting and partitioning pending calls.
+    # Keep it read-only; policy refusals still return through #call as tool results.
+    def approval_resolver
+      ->(call) do
+        next true if @skip_side_effects.include?(call.id.to_s) || provenance_block(call.arguments) || customer_confirm?
+
+        native_approval_decision(call.arguments, call.id)
+      end
+    end
+
+    # The confirmed re-run of a held call (Tools::ConfirmPending): every check but
+    # the hold itself — provenance, approval, fencing, evidence, the side-effect
+    # record and the trace all still apply to the write.
+    def call_confirmed(args) = run(args, hold: false)
+
+    private
+
+    def run(args, hold:, native_call: false)
       # A non-idempotent tool call ALREADY COMPLETED in the interrupted
       # turn -> respond with a marker, NEVER re-execute. The marker returns to
       # the model, keeping the tool-use protocol intact.
       call_id = correlation_id
-      return { "skipped" => "already_executed" } if call_id && @skip_side_effects.include?(call_id)
+      continuation = native_call && @state.approval_continuation
+      if call_id && @skip_side_effects.include?(call_id)
+        halt = continuation && continuation.dig("halts", call_id)
+        return ToolDefinition::Halt.new(content: halt["content"]) if halt
+
+        return { "skipped" => "already_executed" }
+      end
 
       started = monotonic
       if (blocked = provenance_block(args))
@@ -60,28 +118,44 @@ module Insika
         return blocked
       end
 
-      # Approval gate: a tool marked `approval` suspends the turn in
-      # :waiting until the operator resolves it. Delegates to the coordinator (the
-      # Executor), which creates/queries the PendingAction and blocks via the
-      # mailbox. Rejection returns to the MODEL as an error (the turn continues),
-      # it does not bring down the turn. CancelledError/TimeoutError from the wait
-      # propagate (they are not ToolTimeout).
+      # Customer confirmation: the call is recorded and returned to the model as
+      # held; the turn goes on to ask. After the provenance gate (an id the customer
+      # never saw is not put to them as real) and before approval.
+      if hold && (held = confirmation_hold(args))
+        trace(call_id, args, held, started)
+        return held
+      end
+
+      # Native calls recheck the persisted decision after RubyLLM's resolver.
+      # Direct/workflow calls still create and await approval through the mailbox.
+      # Cancellation and turn timeout propagate from that wait (not ToolTimeout).
       if approval_required?
-        decision = @state.approval_coordinator.request_approval(
-          task: @state.task, turn: @state.turn, tool: real_name, args: args, actor: @state.actor
-        )
-        return { error: "rejected by operator" } unless decision.to_s == "approved"
+        approved = if native_call
+          native_approval_decision(args, call_id) == true
+        else
+          @state.approval_coordinator.request_approval(
+            task: @state.task, turn: @state.turn, tool: real_name, args: args, actor: @state.actor
+          ).to_s == "approved"
+        end
+        return { error: "rejected by operator" } unless approved
       end
 
       started = monotonic
-      result = with_gate { Async::Task.current.with_timeout(@timeout, ToolTimeout) { __getobj__.call(args) } }
+      Thread.current[TIMING_KEY] = nil
+      result = with_gate { Async::Task.current.with_timeout(@timeout, ToolTimeout) { invoke(args) } }
       # the ONE seam every tool result passes on its way to the model.
       # For a declared-evidence tool: reshape to the lean envelope, record the ids
       # on the ledger, hoard the attachments. No evidence = the result passes
       # through untouched (one nil-check — parity).
+      capture_shared_result(call_id, result)
       result = process_evidence(result)
       result = fence(result)
-      record_side_effect!(call_id) if side_effect?
+      if side_effect?
+        halt = { "content" => result.content } if continuation && result.is_a?(ToolDefinition::Halt)
+        record_side_effect!(call_id, **(halt ? { halt: halt } : {}))
+        (continuation["halts"] ||= {})[call_id] = halt if halt
+        @skip_side_effects << call_id if native_call
+      end
       trace(call_id, args, result, started)
       result
     rescue ToolTimeout
@@ -90,10 +164,17 @@ module Insika
       err
     end
 
-    private
-
     def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
 
+    def invoke(args)
+      tool = __getobj__
+      if tool.respond_to?(:parameters_schema)
+        tool.call(**args.transform_keys(&:to_sym), tool_call: @state.current_tool_call)
+      else
+        tool.call(args)
+      end
+    end
+
     # with parallel tool calls on, the turn's shared semaphore
     # (TurnState#tool_gate, sized by `limits[:tool_concurrency]`) caps how many run
     # at once. Wraps the REAL call ONLY — the approval wait and the skip check are
@@ -144,11 +225,46 @@ module Insika
     # (DataDefinedTool exposes its definition's schema; a code tool exposes none
     # -> every declared parameter is treated as required).
     def optional_params(tool)
-      return [] unless tool.respond_to?(:params_schema) && (schema = tool.params_schema).is_a?(Hash)
+      return [] unless tool.respond_to?(:parameters_schema) && (schema = tool.parameters_schema).is_a?(Hash)
+
+      schema = Coercion.deep_stringify(schema)
 
       (schema["properties"] || {}).keys.map(&:to_s) - Array(schema["required"]).map(&:to_s)
     end
 
+    def confirmation_hold(args)
+      return unless customer_confirm?
+
+      store = @state.respond_to?(:pending_action_store) ? @state.pending_action_store : nil
+      task = @state.task
+      if store.nil? || task.nil? || task.session_id.nil?
+        # Fail loud, never run: a write that needs the customer's word and has
+        # nowhere to wait for it is a misconfiguration, not a pass.
+        missing = store.nil? ? "no PendingActionStore" : "no session"
+        raise Insika::Error, "tool '#{real_name}' needs the customer's confirmation but the turn has #{missing} to hold it in"
+      end
+
+      id = PendingActionStore.confirmation_id(task.session_id, real_name)
+      store.create(id: id, task_id: task.id, session_id: task.session_id, turn: @state.turn,
+                   tool: real_name, args: args || {}, kind: PendingActionStore::CUSTOMER)
+      @event_stream&.emit(Insika::Event.new(
+        type: :confirmation_requested,
+        data: { pending_id: id, tool: real_name, args: args },
+        meta: { task_id: task.id, session_id: task.session_id }
+      ))
+      # Key order is what the model reads first: the verdict, then the instruction,
+      # then the echo of what it asked for — the echo alone reads like a success.
+      Held[{ "executed" => false, "status" => "pending_confirmation", "gate" => "confirmation",
+             "instruction" => CONFIRMATION_INSTRUCTION, "tool" => real_name, "args" => args,
+             "pending_id" => id }]
+    end
+
+    def customer_confirm?
+      profile = @state.respond_to?(:profile) ? @state.profile : nil
+      list = profile.respond_to?(:customer_confirm) ? profile.customer_confirm : nil
+      Array(list).include?(real_name)
+    end
+
     def emit_blocked(result)
       task = @state.task # nil on a one-shot turn, like `trace` already assumes
       @event_stream&.emit(Insika::Event.new(
@@ -161,16 +277,27 @@ module Insika
     # Records the call for debugging in the Studio (name + model args + result +
     # ms), keyed by the SESSION. Masking/truncation is the ToolTraceStore's job;
     # here we only collect. NEVER breaks the turn (trace is observability).
+    def capture_shared_result(call_id, result)
+      return unless @state.respond_to?(:shared_conversations) && @state.shared_conversations
+
+      @state.shared_conversations.record_tool_result(task: @state.task, call_id: call_id, result: result)
+    end
+
     def trace(call_id, args, result, started)
+      capture_shared_result(call_id, result)
+      timing = Thread.current[TIMING_KEY] || {}
+      Thread.current[TIMING_KEY] = nil
+      ms = started ? ((monotonic - started) * 1000).round : nil
+      TurnTiming.current&.tool(real_name, ToolTraceStore.ok?(result), ms)
       return unless @trace_recorder && @state.task&.session_id
 
       @trace_recorder.record(
         session_id: @state.task.session_id,
-        entry: { "turn" => @state.turn, "tool" => real_name, "call_id" => call_id.to_s,
+        entry: { "task_id" => @state.task.id.to_s, "turn" => @state.turn, "tool" => real_name, "call_id" => call_id.to_s,
                  "args" => args, "result" => result,
-                 "gate" => result.is_a?(Blocked) ? result["gate"] : nil,
-                 "ms" => started ? ((monotonic - started) * 1000).round : nil,
-                 "at" => Time.now.utc.iso8601 }
+                 "gate" => result.is_a?(Blocked) || result.is_a?(Held) ? result["gate"] : nil,
+                 "ms" => ms,
+                 "at" => Time.now.utc.iso8601 }.merge(timing)
       )
     rescue StandardError
       nil
@@ -187,8 +314,18 @@ module Insika
     # Does the current tool require approval? (names come from the Resolution
     # via state).
     def approval_required?
-      @state.respond_to?(:requires_approval) &&
-        Array(@state.requires_approval).include?(real_name)
+      (@state.respond_to?(:requires_approval) && Array(@state.requires_approval).include?(real_name)) ||
+        (__getobj__.respond_to?(:requires_approval?) && __getobj__.requires_approval?)
+    end
+
+    def native_approvals?
+      @state.respond_to?(:native_approvals) && @state.native_approvals == true
+    end
+
+    def native_approval_decision(args, call_id)
+      @state.approval_coordinator.approval_decision(
+        task: @state.task, turn: @state.turn, tool: real_name, args: args, call_id: call_id
+      )
     end
 
     # The call's correlation: the provider id (RubyLLM chat, via
@@ -208,11 +345,11 @@ module Insika
     end
 
     # Written BEFORE the tool result returns to the model.
-    def record_side_effect!(call_id)
+    def record_side_effect!(call_id, **metadata)
       return if call_id.to_s.empty?
 
       @checkpoint_store.record_side_effect(@state.task.id, turn: @state.turn,
-                                                           tool_call_id: call_id)
+                                                           tool_call_id: call_id, **metadata)
     end
 
     # ----   fencing ----------------------------------------------

data/lib/insika/tool_manifest.rb

@@ -73,6 +73,7 @@ module Insika
         "response" => binding[:response],
         "secret_headers" => binding[:secret_headers],
         "side_effect" => t["side_effect"],
+        "timeout" => t["timeout"],
         "group" => t["group"] || defaults["group"],       # per-group allowlist:
         "tags" => (Array(defaults["tags"]) | Array(t["tags"])), # inherited default; tags unioned
         # Per-tool only: "this result ends the turn" is a property of THIS backend's

data/lib/insika/tool_store.rb

@@ -35,6 +35,9 @@ module Insika
     # -> [String] names, lexicographic order.
     def names = @cs.keys(SCOPE)
 
+    # Changes whenever any config is written, in any process (ConfigStore#version_token).
+    def version_token = @cs.version_token
+
     # -> [Hash] MASKED definitions (for the UI).
     def all
       names.filter_map { |n| get(n) }

data/lib/insika/tool_trace_store.rb

@@ -37,6 +37,11 @@ module Insika
       nil
     end
 
+    # Conventional tool error = Hash with key "error"/:error (everything else is ok).
+    def self.ok?(result)
+      !(result.is_a?(Hash) && (result.key?("error") || result.key?(:error)))
+    end
+
     # -> [Hash] session entries in chronological order. [] if none.
     def for_session(session_id) = @store.get(SCOPE, session_id.to_s) || []
 
@@ -49,19 +54,21 @@ module Insika
       e = stringify_keys(entry)
       {
         "turn" => e["turn"], "tool" => e["tool"].to_s, "call_id" => e["call_id"].to_s,
-        "ok" => ok?(e["result"]),
+        "ok" => self.class.ok?(e["result"]),
         "args" => clip(mask(e["args"])), "result" => clip(mask(e["result"])),
         "ms" => e["ms"], "at" => e["at"].to_s
-      }.tap { |trace| trace["gate"] = e["gate"].to_s if e["gate"] }
-    end
-
-    # Conventional tool error = Hash with key "error"/:error (everything else is ok).
-    def ok?(result)
-      !(result.is_a?(Hash) && (result.key?("error") || result.key?(:error)))
+      }.tap do |trace|
+        trace["task_id"] = e["task_id"].to_s if e["task_id"]
+        trace["gate"] = e["gate"].to_s if e["gate"]
+        # Timing breakdown a data-tool reports (see DataDefinedTool#record_timing).
+        %w[pre_ms http_ms server_ms].each { |k| trace[k] = e[k] if e[k].is_a?(Integer) }
+      end
     end
 
     # Masks values of sensitive keys (recursive); the rest pass through intact.
-    def mask(obj)
+    def mask(obj) = self.class.mask(obj)
+
+    def self.mask(obj)
       case obj
       when Hash
         obj.each_with_object({}) do |(k, v), acc|

data/lib/insika/tool_usage_report.rb

@@ -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?
 

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
@@ -49,20 +49,11 @@ module Insika
       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
@@ -72,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.
@@ -90,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
@@ -220,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 }