insika 0.9.0 → 1.0.1

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

@@ -41,14 +41,7 @@ module Insika
 
       def name = @definition.name
       def description = @definition.description
-      def params_schema = @definition.parameters
-
-      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
 
       def execute(**kwargs)
         spec = @definition.presentation

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
 
@@ -319,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
 

data/lib/insika/tools/tool_search.rb

@@ -6,13 +6,13 @@ module Insika
   module Tools
     # Level 2 of TOOLS progressive disclosure (analog of LoadSkill):
     # searches the deferred catalog and PROMOTES the relevant ones into the live chat via
-    # chat.with_tools (verified to propagate on the next round of the same `ask`
-    # in ruby_llm 1.16). `require "ruby_llm"` stays in THIS file (it inherits from
+    # chat.with_tools (propagates on the next round of the same `ask`).
+    # `require "ruby_llm"` stays in THIS file (it inherits from
     # RubyLLM::Tool) — it does not enter lib/insika.rb; the Executor loads it lazily in
     # configure_chat (like LoadSkill).
     class ToolSearch < RubyLLM::Tool
       description "Searches and enables additional tools by describing the need"
-      param :query, desc: "What you need to do (e.g.: 'send email', 'generate invoice')"
+      parameter :query, description: "What you need to do (e.g.: 'send email', 'generate invoice')"
 
       # RubyLLM::Tool#name derives from self.class.name — for a nested class
       # (Insika::Tools::ToolSearch) it produces "insika--tools--tool_search", not
@@ -81,11 +81,13 @@ module Insika
 
       def describe(entry)
         tool = @tool_registry.resolve(entry.name)
+        schema = Coercion.deep_stringify(tool.parameters_schema || {})
         {
           name: entry.name,
           description: entry.description,
-          parameters: tool.parameters.transform_values do |p|
-            { type: p.type, description: p.description, required: p.required }
+          parameters: schema.fetch("properties", {}).to_h do |name, property|
+            [name.to_sym, { type: property["type"], description: property["description"],
+                            required: Array(schema["required"]).include?(name) }]
           end
         }
       rescue Insika::NotFoundError

data/lib/insika/tools/tts.rb

@@ -20,8 +20,8 @@ module Insika
       description "Synthesize speech for the reply — a voice clip travels as an " \
                   "output part in the envelope, the channel supports it. Use when the " \
                   "customer should HEAR the answer rather than read it."
-      param :text, desc: "The words to speak"
-      param :voice, desc: "Optional voice override (default from the agent config)",
+      parameter :text, description: "The words to speak"
+      parameter :voice, description: "Optional voice override (default from the agent config)",
             required: false
 
       def name = "tts"

data/lib/insika/tools/update_briefing.rb

@@ -53,8 +53,8 @@ module Insika
         names.empty? ? BASE_DESCRIPTION : "#{BASE_DESCRIPTION} field must be one of: #{names.join(', ')}."
       end
 
-      param :field, desc: "The briefing field name (one of the declared list)"
-      param :value, desc: "The value learned. Blank clears the field."
+      parameter :field, description: "The briefing field name (one of the declared list)"
+      parameter :value, description: "The value learned. Blank clears the field."
 
       def name = "update_briefing"
 
@@ -72,7 +72,7 @@ module Insika
 
       # The declared names become the `field` enum in the schema the provider
       # sees — per-turn data, like the subagent allowlist (Tools::AgentEnum).
-      def params_schema
+      def parameters_schema
         @field_enum_schema ||= Insika::Tools::AgentEnum.inject(super, @fields, path: %i[field])
       end
 
@@ -99,7 +99,7 @@ module Insika
 
         description "Records the next step agreed with the customer " \
                     "(e.g. 'send the payment link tomorrow at 10'). Blank clears it."
-        param :text, desc: "The agreed next step, in one sentence"
+        parameter :text, description: "The agreed next step, in one sentence"
 
         def name = "set_next_step"
 

data/lib/insika/turn_output.rb

@@ -49,12 +49,12 @@ module Insika
     # public_intermediate: the agent opted this channel in (`edge_stream`), so the
     #   narration is TAGGED and `/v1/responses` gives it its own frame. Default false:
     #   an internal event stays internal unless someone said otherwise.
-    def initialize(filter:, emit:, public_intermediate: false)
+    def initialize(filter:, emit:, public_intermediate: false, halt_text: "")
       @filter = filter
       @emit = emit
       @public_intermediate = public_intermediate
       @pending = +""           # text of the message currently streaming
-      @last_intermediate = +"" # text of the last message that turned out NOT to be the answer
+      @last_intermediate = halt_text.to_s # already filtered when checkpointed
       @candidate = nil
     end
 

data/lib/insika/turn_state.rb

@@ -6,6 +6,10 @@ module Insika
   class TurnState
     attr_reader :task, :profile, :turn # turn identity (1-based)
     attr_accessor :message,            # input (Middleware may rewrite)
+                  :caller_context,     # payload `context`: text the caller sends WITH the message
+                  #                      (channel rules, what the customer already saw). The model
+                  #                      and the transcript get it ahead of the message; guardrails
+                  #                      and retrieval read `message` alone. nil = none.
                   :context,            # ContextPackage from the Builder
                   :allowed_tools,      # Resolution from the Policy Engine
                   :allowed_skills,
@@ -111,7 +115,9 @@ module Insika
     # to serialize the turn's real exchange — user + assistant(tool_calls) + tool
     # results + final assistant — into the transcript. nil = no chat recorded
     # (workflow/halt) → persist_turn falls back to the {user, assistant} pair.
+    attr_accessor :shared_conversations
     attr_accessor :chat_baseline
+    attr_accessor :tool_halt
 
     # Internal: impl_name(String) -> STABLE name of the capability that
     # resolved it, computed by resolve_capabilities BEFORE the policy_request and
@@ -141,6 +147,9 @@ module Insika
     # Internal (memory): the turn's tenant (from the Command), scope of the write path
     # (`remember` tool). Set in run_pipeline; nil = DEFAULT_TENANT in the MemoryStore.
     attr_accessor :tenant
+    # The phrase an injection-flagging InputGuardrail matched (nil = none). The
+    # ChatBuilder hands the model a per-turn notice built from it.
+    attr_accessor :security_notice
 
     # Internal: turn context deposited into the data-tools to
     # resolve {{ctx.*}} (chat_id/agent_id/tenant/store_id) and emit
@@ -155,6 +164,9 @@ module Insika
     # (workflow) or provider without counts.
     attr_accessor :usage
 
+    # Native rerank usage events, separate from the chat/Responses token totals.
+    attr_accessor :rerank_usage
+
     # Internal (Tool Search): ids of side-effects already completed in the
     # interrupted turn, propagated to the tools PROMOTED by tool_search (the same `skip`
     # that the eager tools' wrap_tools receives). Set in run_pipeline;
@@ -166,6 +178,12 @@ module Insika
     # creates the PendingAction/suspends/waits; `actor` = the turn's mailbox (used
     # by the coordinator for await(:approval)).
     attr_accessor :requires_approval, :approval_coordinator, :actor
+    attr_accessor :native_approvals, :approval_continuation, :turn_output
+
+    # Customer confirmation: the store a `customer_confirm` call is held in by the
+    # ToolEnvelope and resolved from by confirm_pending/cancel_pending. nil = the
+    # deployment has no PendingActionStore (a hold then fails loud, like approval).
+    attr_accessor :pending_action_store
 
     # Internal: the turn's shared in-flight cap for tool calls —
     # ONE Async::Semaphore(tool_concurrency), installed by ToolAssembly#wrap_tools

data/lib/insika/turn_timing.rb

@@ -1,15 +1,16 @@
 # frozen_string_literal: true
 
 module Insika
-  # Opt-in per-turn latency breakdown (locate the
-  # TTFB cost with real-turn data). OFF unless INSIKA_TURN_TIMING is set — when
-  # off the Executor never allocates one and the hot path pays only `nil&.mark`.
+  # Per-turn latency clock. Every turn runs one (a few clock reads); the turn's
+  # numbers land in ModelMetricsStore's turn rows (#metrics). INSIKA_TURN_TIMING
+  # only decides what the RESPONSE exposes (#to_h) and whether store calls count.
   #
   # Splits a turn into the three windows that answer "is TTFB local or provider?":
   #   prep_ms  — prep_start -> ask: ALL local work before the provider call
   #              (context build, policy, guardrail detectors, chat assembly).
   #   ttft_ms  — ask -> first_token: the provider round-trip to the 1st token.
   #   gen_ms   — first_token -> done: streaming the rest of the response.
+  #   store_calls — store calls this turn made (+ store_calls_by: "op scope" => n).
   #
   # Marks are monotonic; `mark` is first-write-wins so `first_token` records the
   # FIRST content chunk even though it is called on every chunk.
@@ -26,26 +27,35 @@ module Insika
       Insika::EnvSchema.truthy?(Insika::EnvSchema.read("INSIKA_TURN_TIMING", env))
     end
 
-    # The marks that only mean something under INSIKA_TURN_TIMING. A `breakdown:
-    # false` clock (a channel turn with the flag off) ignores them and measures
-    # only first_balloon_ms.
-    BREAKDOWN_MARKS = %i[prep_start ask first_token done].freeze
-    private_constant :BREAKDOWN_MARKS
+    # Fiber-storage slot holding the running turn's clock. Child fibers (parallel
+    # tool calls, context providers) inherit it, so their store calls count too.
+    FIBER_KEY = :insika_turn_timing
 
-    # breakdown: true (the default) is the flag-on clock: prep/ttft/gen/total.
-    # false is the   channel clock: only :inbound -> :first_balloon,
-    # so a channel turn with the flag off still answers H-latência.
+    def self.current = Fiber[FIBER_KEY]
+
+    # "config:<scope>" keeps its config scope; any other scope keeps its first
+    # segment, so ids embedded in scope names do not split the breakdown.
+    def self.scope_group(scope)
+      parts = scope.to_s.split(":")
+      parts.first == "config" ? parts.first(2).join(":") : parts.first.to_s
+    end
+
+    # breakdown: true (the default) exposes prep/ttft/gen/total in #to_h.
+    # false exposes only first_balloon_ms (the flag-off contract); every mark is
+    # still taken, so #metrics is complete either way.
     def initialize(breakdown: true)
       @marks = {}
       @breakdown = breakdown
+      @tools = []
     end
 
     def mark(name)
-      return unless @breakdown || !BREAKDOWN_MARKS.include?(name)
-
       @marks[name] ||= Process.clock_gettime(Process::CLOCK_MONOTONIC)
     end
 
+    # One tool call of this turn (ToolEnvelope#trace): [name, ok, ms].
+    def tool(name, ok, ms) = @tools << [name.to_s, ok, ms]
+
     # Has this mark fired? Used by `SendMessage` to prove the channel clock was
     # stamped at 202 acceptance (`:inbound` before the debounce window), and by
     # the pipeline to know a threaded clock already started.
@@ -56,13 +66,40 @@ module Insika
     # first_balloon_ms is the inbound -> first outbox flush window.
     # A missing number is never a zero — no mark, no key.
     def to_h
-      {
+      h = {
         prep_ms: delta(:prep_start, :ask),
         ttft_ms: delta(:ask, :first_token),
         gen_ms: delta(:first_token, :done),
         total_ms: delta(:prep_start, :done),
         first_balloon_ms: delta(:inbound, :first_balloon)
       }.compact
+      h = h.slice(:first_balloon_ms) unless @breakdown
+      return h unless @store_calls
+
+      h.merge(store_calls: @store_calls.values.sum,
+              store_calls_by: @store_calls.sort_by { |call, n| [-n, call] }.to_h)
+    end
+
+    # The turn row ModelMetricsStore keeps: every window, whatever the flag.
+    # queue_ms is inbound -> pipeline start (debounce + FIFO wait), the part of
+    # first_balloon_ms that is not the turn's own work. tools_ms sums the calls,
+    # so parallel calls count more than their wall time.
+    def metrics
+      {
+        "prep_ms" => delta(:prep_start, :ask), "ttft_ms" => delta(:ask, :first_token),
+        "gen_ms" => delta(:first_token, :done), "total_ms" => delta(:prep_start, :done),
+        "first_balloon_ms" => delta(:inbound, :first_balloon), "queue_ms" => delta(:inbound, :prep_start),
+        "tools_ms" => (@tools.sum { |_, _, ms| ms.to_i } unless @tools.empty?),
+        "tools" => (@tools unless @tools.empty?)
+      }.compact
+    end
+
+    # One store call made during this turn (see Stores::TurnCounter).
+    def count_store(op, scope)
+      return unless @breakdown
+
+      @store_calls ||= Hash.new(0)
+      @store_calls["#{op} #{self.class.scope_group(scope)}"] += 1
     end
 
     private

data/lib/insika/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Insika
-  VERSION = "0.9.0"
+  VERSION = "1.0.1"
 end