insika 0.3.0 → 0.8.0

data/lib/insika/agent_profile.rb

@@ -128,6 +128,12 @@ module Insika
     #                                   event the consumer acts on). Same opt-in as
     #                                   `memory`. What "stuck" MEANS is the consumer's call
     #                                   (escalation via CRM/operator), never the engine's.
+    :stt_prompt,                     # STT vocabulary hint (WS9): domain words
+    #                                   (product names, brand terms) the transcriber should
+    #                                   expect on this agent's voice notes — passed straight
+    #                                   through to the Whisper-family provider's `prompt:`.
+    #                                   nil/absent = the deployment default (INSIKA_STT_PROMPT
+    #                                   env) or nothing. OPERATOR config, never customer input.
     :outputs,                         # generated-media output policy (WS9, saída):
     #                                   { "image" => { "model" => …, "size" => "1024x1024" },
     #                                   "tts" => { "model" => "tts-1", "voice" => "alloy",
@@ -244,20 +250,50 @@ module Insika
                                    # off (parity, byte-identical engine). Shape-validated by
                                    # the command/engine, never here (the refinement precedent).
                                    # Deep-stringified like the other free-form hashes.
-    :harvest                         # the gated-harvest declaration — pack data,
-                                   # exactly like refinement/distill:
-                                   # { "enabled" => bool,
-                                   #   "negative_list" => [ { "rule" => "…", "pattern" => "…",
-                                   #                          "note" => "…" } ],
-                                   #   "miner" => { "model" => "<ref — absent = the platform
-                                   #       utility_model>", "window" => { "last_sessions" => N },
-                                   #       "max_proposals" => N, "budget" => { "tokens" => N } },
-                                   #   "idle_hours" => 24, "min_messages" => 3 }.
-                                   # The ENGINE mines (reads sessions, asks the miner, filters
-                                   # through the negative list + grounding), never authors a
-                                   # rule (D4). nil/absent = the loop is off (parity).
-                                   # Shape-validated by the command/engine/doctor, never here.
+    :harvest,                        # the gated-harvest declaration — pack data,
+                                     # exactly like refinement/distill:
+                                     # { "enabled" => bool,
+                                     #   "negative_list" => [ { "rule" => "…", "pattern" => "…",
+                                     #                          "note" => "…" } ],
+                                     #   "miner" => { "model" => "<ref — absent = the platform
+                                     #       utility_model>", "window" => { "last_sessions" => N },
+                                     #       "max_proposals" => N, "budget" => { "tokens" => N } },
+                                     #   "idle_hours" => 24, "min_messages" => 3 }.
+                                     # The ENGINE mines (reads sessions, asks the miner, filters
+                                     # through the negative list + grounding), never authors a
+                                     # rule (D4). nil/absent = the loop is off (parity).
+                                     # Shape-validated by the command/engine/doctor, never here.
+                                     # Deep-stringified like the other free-form hashes.
+    :knowledge,                       # the post-turn learning declaration — pack
+                                   # data, exactly like distill/harvest:
+                                   # { "extract" => true, "retrieve" => true,
+                                   #   "model" => "<ref — absent = the platform
+                                   #       utility_model>", "top_k" => 5,
+                                   #   "index" => "scan", "types" => ["fact", …] }.
+                                   # The ENGINE extracts concepts after the turn and
+                                   # stamps their provenance/confidence/sources;
+                                   # the model only names concepts (same D1
+                                   # discipline as distill). nil/absent = the
+                                   # loop is off (parity). Shape-validated by
+                                   # the extractor/doctor, never here.
                                    # Deep-stringified like the other free-form hashes.
+    :schedules                       # the recurring-schedule declarations — pack
+                                     # data, exactly like followup/distill:
+                                     # [ { "id" => "daily_report",
+                                     #     "cron" | "every" => …,
+                                     #     "tz" => "America/Sao_Paulo",
+                                     #     "message" => "<the synthetic inbound>",
+                                     #     "session_mode" => "new"|"fixed",
+                                     #     "overrides" => { "turn_timeout" => N,
+                                     #                        "max_tool_calls" => N,
+                                     #                        "model" => … },
+                                     #     "enabled" => bool }, … ].
+                                     # The ENGINE owns the firing (the
+                                     # ScheduleEngine, the tick's duty); the
+                                     # store rows are declared-derived.
+                                     # Shape-validated by Insika::Schedule,
+                                     # never here. nil/empty = the feature is
+                                     # off for that agent (parity).
   )
 
   # Reopened class (not a Data.define block): a constant assigned inside
@@ -289,15 +325,17 @@ module Insika
                     params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
                     refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {},
                      budget: nil, reliability: nil, alerts: nil, routes: nil, stuck_signal: nil,
-                     outputs: nil, briefing_fields: nil, grounding: nil, funnel: nil,
-                     followup: nil, distill: nil, harvest: nil)
+outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil,
+                      followup: nil, distill: nil, harvest: nil, knowledge: nil, schedules: nil)
       new(
         id: id, model: model, provider: provider, base_prompt: base_prompt,
         prompt_files: Array(prompt_files), tools_allow: tools_allow,
         tools_deny: Array(tools_deny), tools_allow_groups: tools_allow_groups, skills: skills,
         skills_eager: skills_eager,
         context_providers: context_providers, workflows_allow: workflows_allow,
-        policies: Array(policies), prompt_refs: Array(prompt_refs),
+        policies: normalize_policies(policies, tools_allow: tools_allow, tools_deny: tools_deny,
+                                     tools_allow_groups: tools_allow_groups),
+        prompt_refs: Array(prompt_refs),
         limits: DEFAULT_LIMITS.merge(limits), approvals_required: approvals_required,
         capabilities: capabilities,
         # opt-in like capabilities: nil => NONE. Array-normalize a present value so
@@ -326,6 +364,9 @@ module Insika
         routes: Coercion.deep_stringify(routes),
         stuck_signal: stuck_signal,
         outputs: Coercion.deep_stringify(outputs),
+        # plain vocabulary string, like `base_prompt` — no deep_stringify (not
+        # a Hash/Array). "" round-trips as nil (Coercion.presence).
+        stt_prompt: Coercion.presence(stt_prompt),
         # Flat [String] — same discipline as capabilities_declared: a
         # symbol/string mix would be a silent miss in the provider's known-set.
         briefing_fields: normalize_briefing_fields(briefing_fields),
@@ -348,10 +389,51 @@ module Insika
         # harvest is profile DATA, deep-stringified like the other
         # free-form hashes; shape-validated by the command/engine/doctor
         # (never here — the refinement precedent). nil = off (parity).
-        harvest: Coercion.deep_stringify(harvest)
+        harvest: Coercion.deep_stringify(harvest),
+        # knowledge is profile DATA, deep-stringified like the other
+        # free-form hashes; shape-validated by the extractor/doctor
+        # (never here — the refinement precedent). nil = off (parity).
+        knowledge: Coercion.deep_stringify(knowledge),
+        # schedules is profile DATA, deep-stringified like the other
+        # free-form hashes (an ARRAY of declarations); parsed into
+        # Insika::Schedule entries by the engine/doctor/Studio (shape-validated
+        # THERE, never here). nil/[] = the feature is off (parity).
+        schedules: normalize_schedules(schedules)
       )
     end
 
+    # Declaring a tool allow/deny list IS opting into it. The list is only ever
+    # applied by the builtin `tool_allowlist` policy, and the Policy::Engine runs
+    # ONLY the policies a profile names — so a profile with `tools_allow: [a, b]`
+    # and no policies sent EVERY registered tool to the model, silently. A
+    # declared allowlist that does nothing is the failure mode; same rule as the
+    # "mcp:<name>" group auto-added to `tools_allow_groups` by the DSL.
+    #
+    # Presence, not emptiness, is the trigger for the two nil-able lists:
+    # `tools_allow: []` means "no tools" and must enforce just as hard.
+    # `tools_deny` has no nil state (it defaults to []), so only a non-empty
+    # deny list counts as a declaration.
+    #
+    # Appended, never prepended: profile-declared policies keep their order. The
+    # engine intersects allows and unions denies, so position changes only the
+    # audit order, not the outcome.
+    def self.normalize_policies(policies, tools_allow:, tools_deny:, tools_allow_groups:)
+      names = Array(policies)
+      declared = !tools_allow.nil? || !tools_allow_groups.nil? || !Array(tools_deny).empty?
+      return names unless declared && names.none? { |n| n.to_s == "tool_allowlist" }
+
+      names + ["tool_allowlist"]
+    end
+
+    # nil/absent -> nil; a single Hash -> [Hash]; else an Array of Hashes —
+    # deep-stringified so JSON round-trips stay stable.
+    def self.normalize_schedules(list)
+      return nil if list.nil?
+
+      entries = list.is_a?(Hash) ? [list] : Array(list)
+      entries.empty? ? nil : Coercion.deep_stringify(entries)
+    end
+
     # nil -> []; strings; trim + drop empties + uniq (stable order); every name
     # must match ToolDefinition::NAME_RE (\A[a-z][a-z0-9_]*\z) or it is a
     # ValidationError at build time — the names become tool-description text,

data/lib/insika/artifact_signing.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "time"
+
+module Insika
+  # The signed-link half of the artifact serving surface. The signing key
+  # lives in the environment (INSIKA_ARTIFACT_SIGNING_KEY), never in a store:
+  # HMAC-SHA256 over (id, expiry), verified in constant time on the serve
+  # path. Without the key, only the authenticated Studio URL exists.
+  #
+  # The token is deterministic for a (id, expiry) pair — no nonce, on purpose:
+  # a rotated key invalidates every outstanding link, which is the documented
+  # rotation behavior (an artifact link is short-lived by TTL, not by
+  # unguessability of a single-use nonce).
+  module ArtifactSigning
+    module_function
+
+    # The route's path shapes — the ONE place the URL grammar lives, shared
+    # by the tool (which hands URLs to the model) and the route (which serves
+    # them).
+    AUTHENTICATED_PATH = "/studio/artifacts/%{id}/content"
+    SIGNED_PATH = "/studio/artifacts/s/%{id}?exp=%{exp}&sig=%{sig}"
+
+    # -> hex token (64 chars) | nil when the key is blank (no signed surface).
+    def sign(id:, expires_at:, key:)
+      key = key.to_s
+      return nil if key.empty?
+
+      OpenSSL::HMAC.hexdigest("SHA256", key, payload(id, expires_at))
+    end
+
+    # -> bool. Re-signs the (id, exp) pair the route extracted from the URL
+    # and compares in constant time; an expired link or a blank key/token is
+    # false (the route 404s — no oracle). Expiry is inclusive: a link at its
+    # exact `expires_at` still verifies.
+    def valid?(id:, token:, key:, exp:, now: Time.now.utc)
+      token = token.to_s
+      key = key.to_s
+      return false if key.empty? || token.empty?
+
+      expected = sign(id: id.to_s, expires_at: exp, key: key)
+      return false unless expected && secure_compare(expected, token)
+
+      exp_time = exp.is_a?(Time) ? exp.to_time.utc : Time.iso8601(exp.to_s).utc
+      now.to_time <= exp_time
+    rescue ArgumentError, TypeError
+      false # a malformed exp (or a time that never parses) is an invalid link
+    end
+
+    # -> the artifact's shareable URL. With a key + ttl: the signed link
+    # (shares OUTSIDE the Studio, expires). Without: the authenticated Studio
+    # content URL. An empty base yields the relative path — still openable in
+    # the Studio, useless on a channel (the doc says exactly that).
+    def url_for(id:, base: nil, key: nil, ttl: nil, now: Time.now.utc)
+      base = base.to_s.sub(%r{/\z}, "")
+      if key && key.to_s.length.positive? && ttl && ttl.to_i.positive?
+        exp = (now.to_time + ttl.to_i).utc.iso8601
+        sig = sign(id: id.to_s, expires_at: exp, key: key)
+        "#{base}#{format(SIGNED_PATH, id: id, exp: exp, sig: sig)}"
+      else
+        "#{base}#{format(AUTHENTICATED_PATH, id: id)}"
+      end
+    end
+
+    # Constant-time comparison of two hex strings. Length-independent compare
+    # is fine here: the token length is public (fixed by the algorithm).
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      a.bytes.zip(b.bytes).reduce(0) { |acc, (x, y)| acc | (x ^ y) }.zero?
+    end
+
+    # The signed payload: id + expiry — both are what the route must not let
+    # an attacker change. The id is the store key; the expiry bounds the link.
+    # Accepts a Time or an ISO8601 String (the route passes the query param).
+    def payload(id, expires_at)
+      time = expires_at.is_a?(Time) ? expires_at.utc : Time.iso8601(expires_at.to_s).utc
+      "#{id}:#{time.iso8601}"
+    end
+  end
+end

data/lib/insika/artifact_store.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "time"
+
+module Insika
+  # The report destination: one record per run, no versioning, the listing
+  # IS the history. A store, not a CMS.
+  #
+  # The tenant is a BINDING of the row — inherited from the agent that saved
+  # the artifact (the tool reads it from the turn context, never from the
+  # model), so a purge is a tenant-prefix scan and store A's report can never
+  # appear in, or be linked from, store B.
+  #
+  # Record key: "<tenant>:<agent>:<id>" — per-tenant / per-agent scans are
+  # prefixes; the id is the LAST segment, so a find is a suffix match (the
+  # followup_store.rb idiom — there is no stable prefix for an id alone).
+  # Blank tenant -> the literal "platform" (the outcome_store.rb rule, so the
+  # purge prefix scans line up).
+  class ArtifactStore
+    SCOPE = "artifacts"
+
+    # The mime allowlist — a page, not an attachment: no binaries, no uploads.
+    MIMES = %w[text/html text/markdown image/svg+xml].freeze
+
+    # The size cap on `content` (INSIKA_ARTIFACT_MAX_BYTES; the audio-message
+    # precedent is 1 MB — an artifact is a page, not an attachment).
+    DEFAULT_MAX_BYTES = 1_000_000
+    TITLE_MAX = 200
+
+    Record = Data.define(:id, :tenant, :agent, :task_id, :title, :mime,
+                         :content, :created_at)
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # -> Record. Validates the mime allowlist, a non-empty title (<= 200
+    # chars) and content within `max_bytes` — ValidationError otherwise (the
+    # tool returns it to the model as `{ error: }`).
+    def create(tenant:, agent:, task_id:, title:, mime:, content:,
+               id: SecureRandom.uuid, now: Time.now.utc, max_bytes: DEFAULT_MAX_BYTES)
+      mime = "text/html" if mime.to_s.empty?
+      raise Insika::ValidationError, "mime must be one of #{MIMES.join(', ')}, got #{mime.inspect}" unless MIMES.include?(mime.to_s)
+
+      title = title.to_s
+      raise Insika::ValidationError, "title is required (1..#{TITLE_MAX} chars)" if title.strip.empty? || title.length > TITLE_MAX
+
+      content = content.to_s
+      raise Insika::ValidationError, "content is required" if content.empty?
+      raise Insika::ValidationError, "content exceeds #{max_bytes} bytes (#{content.bytesize})" if content.bytesize > max_bytes
+
+      record = { "id" => id.to_s, "tenant" => tenant_id(tenant), "agent" => agent.to_s,
+                 "task_id" => task_id.to_s, "title" => title, "mime" => mime.to_s,
+                 "content" => content, "created_at" => now.iso8601 }
+      @store.set(SCOPE, key(record), record)
+      to_record(record)
+    end
+
+    # -> Record | nil. Suffix match over the scope's keys (no stable prefix
+    # for an id alone — the followup_store.rb idiom).
+    def find(id)
+      key = @store.list(SCOPE).find { |k| k.end_with?(":#{id}") }
+      key && to_record(@store.get(SCOPE, key))
+    end
+
+    # -> [Record] — one agent's artifacts, newest first (the listing IS the
+    # history; the Studio tab's read).
+    def for_agent(tenant:, agent:)
+      prefix = "#{tenant_id(tenant)}:#{agent}:"
+      @store.list(SCOPE).filter_map do |k|
+        next unless k.start_with?(prefix)
+
+        to_record(@store.get(SCOPE, k))
+      end.sort_by { |r| [r.created_at.to_s, r.id] }.reverse
+    end
+
+    # -> [Record] — EVERY agent's artifacts for the tenant, newest first (same
+    # prefix scan as #purge, but reads instead of deletes). Needs the CALLER
+    # to know the right tenant string — see #all below for the Studio, which
+    # doesn't.
+    def for_tenant(tenant:)
+      prefix = "#{tenant_id(tenant)}:"
+      @store.list(SCOPE).filter_map do |k|
+        next unless k.start_with?(prefix)
+
+        to_record(@store.get(SCOPE, k))
+      end.sort_by { |r| [r.created_at.to_s, r.id] }.reverse
+    end
+
+    # -> [Record] — every artifact in the store, optionally narrowed to one
+    # agent, with NO tenant guess. For the Studio only: it is already
+    # operator-only (sees every tenant's agents), and unlike #for_agent/
+    # #for_tenant (hot, tenant-scoped runtime paths that a real multi-tenant
+    # caller uses because it KNOWS its own tenant) the Studio often does not
+    # — `save_artifact` binds tenant from the turn (`agent` when the Playground
+    # dispatched it, `"platform"` for a plain single-tenant API turn), so a
+    # page guessing one fixed string is wrong for the other half of the time.
+    # Filtering by the record's own `agent` field sidesteps the guess entirely.
+    def all(agent: nil)
+      @store.list(SCOPE).filter_map do |k|
+        record = to_record(@store.get(SCOPE, k))
+        next if record.nil?
+        next if agent && record.agent != agent.to_s
+
+        record
+      end.sort_by { |r| [r.created_at.to_s, r.id] }.reverse
+    end
+
+    # -> bool (did it exist?).
+    def delete(id)
+      key = @store.list(SCOPE).find { |k| k.end_with?(":#{id}") }
+      key ? @store.delete(SCOPE, key) : false
+    end
+
+    # -> count removed. The tenant-erasure reach — one tenant's artifacts die
+    # with it, never a neighbour's.
+    def purge(tenant:)
+      prefix = "#{tenant_id(tenant)}:"
+      keys = @store.list(SCOPE).select { |k| k.start_with?(prefix) }
+      keys.each { |k| @store.delete(SCOPE, k) }
+      keys.size
+    end
+
+    # -> count removed. The retention knob's reach (`artifact_ttl_days`) —
+    # the guarantee that PII inside a report expires even though no reader
+    # can see inside the opaque HTML.
+    def delete_older_than(time)
+      cutoff = time.utc.iso8601
+      removed = 0
+      @store.list(SCOPE).each do |k|
+        record = @store.get(SCOPE, k)
+        next unless record && record["created_at"].to_s < cutoff
+
+        @store.delete(SCOPE, k)
+        removed += 1
+      end
+      removed
+    end
+
+    private
+
+    def key(record)
+      "#{record['tenant']}:#{record['agent']}:#{record['id']}"
+    end
+
+    def tenant_id(tenant)
+      t = tenant.to_s
+      t.empty? ? "platform" : t
+    end
+
+    def to_record(rec)
+      return nil if rec.nil?
+
+      Record.new(id: rec["id"], tenant: rec["tenant"], agent: rec["agent"],
+                 task_id: rec["task_id"], title: rec["title"], mime: rec["mime"],
+                 content: rec["content"], created_at: rec["created_at"])
+    end
+  end
+end

data/lib/insika/channel_delivery.rb

@@ -17,7 +17,7 @@ module Insika
   #      party with outages, so "keep trying" is a real requirement and "keep trying
   #      forever" is a real outage of ours.
   #
-  # It is NOT a job queue: no scheduler, no priorities, no fan-out. The moment it
+  # It is NOT a job queue: no priorities, no fan-out. The moment it
   # grows one, the thing to do is take a real queue, not to finish building this.
   class ChannelDelivery
     MAX_ATTEMPTS = 3

data/lib/insika/chat_builder.rb

@@ -15,7 +15,7 @@ module Insika
     def initialize(tool_registry:, skill_catalog:, checkpoint_store:, event_stream:,
                    hooks:, tool_catalog: nil, memory_store: nil, subagent_runner: nil,
                    tool_trace_store: nil, media_runner: nil, session_store: nil,
-                   contact_store: nil, followup_store: nil)
+                   contact_store: nil, followup_store: nil, knowledge_store: nil)
       @tool_registry = tool_registry
       @skill_catalog = skill_catalog
       @checkpoint_store = checkpoint_store
@@ -23,6 +23,10 @@ module Insika
       @hooks = hooks
       @tool_catalog = tool_catalog
       @memory_store = memory_store
+      # load_knowledge is the knowledge-read system tool — wired only with
+      # @knowledge_store present AND profile.knowledge["retrieve"] (a double
+      # gate, like remember). nil = never wired (parity).
+      @knowledge_store = knowledge_store
       # only to trace load_skill, which is not enveloped — nil = no trace (parity).
       @tool_trace_store = tool_trace_store
       # the object exposing #run_subagent (the Executor). nil = the
@@ -104,6 +108,15 @@ module Insika
                                      event_stream: @event_stream, state: state)
       end
 
+      # load_knowledge is a system default (outside the allowlist), like
+      # load_skill — wired only with @knowledge_store present AND the
+      # profile's opt-in (double gate, like remember). Reads the same
+      # (agent, tenant) scope the Knowledge context provider searches.
+      if @knowledge_store && Coercion.truthy?(state.profile.knowledge&.dig("retrieve"))
+        tools << Tools::LoadKnowledge.new(@knowledge_store, state.profile.id, tenant: state.tenant,
+                                          trace_recorder: @tool_trace_store, state: state)
+      end
+
       # update_briefing / set_next_step are the briefing-write system tools
       #  — wired only with @session_store present AND
       # profile.briefing_fields non-empty (double gate, like remember). Never
@@ -319,20 +332,29 @@ module Insika
     end
 
     # RubyLLM's additive callbacks become events. load_skill becomes
-    # :skill_activated. Adds the max_tool_calls counter: the loop is RubyLLM's;
-    # here we only count and abort.
+    # :skill_activated. Hangs the turn's TurnBudget on them: the loop is
+    # RubyLLM's; here we only count, warn and abort.
     def wire_callbacks(chat, state, emit)
-      # Per-TURN counter: safe as a closure local even under concurrent tool calls
-      # (MRI fibers do not preempt between the read and the write). The per-CALL
-      # correlation is NOT — it lives in fiber storage behind TurnState, because
-      # each call gets its own fiber once tool concurrency is on.
-      tool_calls = 0
-      max_tool_calls = state.profile.limits[:max_tool_calls] || 50
+      # The turn's ONE tool-call counter. Safe as a closure-held object even
+      # under concurrent tool calls (MRI fibers do not preempt between the read
+      # and the write). The per-CALL correlation is NOT — it lives in fiber
+      # storage behind TurnState, because each call gets its own fiber once tool
+      # concurrency is on.
+      #
+      # It counts, warns at 10/5/2 calls remaining, and raises the
+      # `stage: :tool_limit` abort — the guard-rail that used to be inline here.
+      # Announcing the budget needs #add_message at the batch boundary; a chat
+      # without it (smoke shim, minimal double) still gets the count and the
+      # abort, just no notice.
+      budget = Insika::TurnBudget.new(
+        chat: chat, max: state.profile.limits[:max_tool_calls] || 50, emit: emit
+      )
 
       # the loop detector. Needs #after_message + #add_message for the
       # batch-boundary intervention; a chat without them (smoke shim, minimal
       # double) stays bounded by max_tool_calls alone — never half-wired.
-      detector = if %i[after_message add_message].all? { |m| chat.respond_to?(m) }
+      appendable = %i[after_message add_message].all? { |m| chat.respond_to?(m) }
+      detector = if appendable
                    repeat = state.profile.limits[:max_tool_repeat] || Insika::AgentProfile::DEFAULT_LIMITS[:max_tool_repeat]
                    Insika::LoopDetector.new(chat: chat, limit: repeat, emit: emit) if repeat >= 2
                  end
@@ -342,11 +364,7 @@ module Insika
         state.current_tool_call = tool_call
         # max_tool_calls guard-rail: stays inline (not as a registered hook)
         # because Hooks is shared across turns and has no unregister.
-        tool_calls += 1
-        if tool_calls > max_tool_calls
-          raise Insika::TimeoutError.new("tool call limit exceeded (#{max_tool_calls})",
-                                           stage: :tool_limit)
-        end
+        budget.tool_call
 
         # AFTER the count, BEFORE the call runs — a post-warning
         # repeat raises here, so the stubborn loop pays for no extra call.
@@ -362,9 +380,16 @@ module Insika
         # under concurrency `after_tool_result` labelled every result with whichever
         # call started last.
         state.current_tool_name = tool_call.name.to_s
-        if state.current_tool_name == "load_skill"
+        case state.current_tool_name
+        when "load_skill"
           args = tool_call.arguments || {}
           emit.call(:skill_activated, { name: args["name"] || args[:name] })
+        when "load_knowledge"
+          # The adoption risk is the model never calling this tool, not what
+          # it injects — so the metric here is retrieval CALLS, tracked at
+          # the same point :skill_activated is.
+          args = tool_call.arguments || {}
+          emit.call(:knowledge_retrieved, { name: args["name"] || args[:name], agent: state.profile.id })
         else
           emit.call(:tool_call, { name: tool_call.name, arguments: tool_call.arguments })
         end
@@ -374,13 +399,19 @@ module Insika
         # the RAW result — the only place a Tool::Halt (halt_when) is
         # still recognizable, and a halted batch must receive no intervention.
         detector&.tool_result(result)
+        budget.tool_result(result)
         result = @hooks.run_after(:tool, result)
         emit.call(:tool_result, { name: state.current_tool_name, result: result.to_s })
       end
 
-      # the intervention appends at the batch boundary (the Nth tool
-      # result closing) — never between two tool results of one batch.
-      chat.after_message { |message| detector.message_ended(message) } if detector
+      # both appends land at the batch boundary (the Nth tool result closing) —
+      # never between two tool results of one batch.
+      return unless appendable
+
+      chat.after_message do |message|
+        detector&.message_ended(message)
+        budget.message_ended(message)
+      end
     end
   end
 end

data/lib/insika/commands/agent_payload.rb

@@ -13,9 +13,9 @@ module Insika
                   tools_allow_groups skills skills_eager context_providers workflows_allow policies
                   prompt_refs limits approvals_required capabilities subagents tools_deferred
                   memory prompt_caching tool_persistence tool_output_compression budget reliability alerts
-                  routes stuck_signal outputs briefing_fields grounding funnel followup
+                  routes stuck_signal outputs stt_prompt briefing_fields grounding funnel followup
                   params model_policy guardrails refinement capabilities_declared
-                  edge_stream metadata distill harvest].freeze
+                  edge_stream metadata distill harvest knowledge schedules].freeze
 
       module_function